Running in a fully self contained file

[charaf-rezrazi-deel]

Hey friends

I have a question on how something like this can be achieved:

#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning

import * as fs from "node:fs";
import { Command, Flags, execute, Plugin } from "@oclif/core";

class LS extends Command {
	static override description = "List the files in a directory.";
	static override flags = {
		version: Flags.version(),
		help: Flags.help(),
		dir: Flags.string({
			char: "d",
			default: process.cwd(),
		}),
	};

	async run() {
		const { flags } = await this.parse(LS);
		const files = fs.readdirSync(flags.dir);
		for (const f of files) {
			this.log(f);
		}
	}
}

await execute({
	dir: import.meta.url,
	loadOptions: {
                // ability to manually pass the commands here, perhaps a "manual" strategy
		commands: [() => new LS()],
	},
	development: true,
});

The idea is for me to completely sever the requirement of an external file (package.json) for oclif to find it's configuration

It would be a perfect scenario if I'm able to instanciate the root plugin programatically

However my first approach seems to be hacky, I started going down the rabbit hole by creating a fake root plugin too:

const plugin = new Plugin({
	root: "my-root",
});

plugin.root = __dirname;

plugin.pjson = {
	version: "0.0.1",
	name: "my-cli",
	oclif: {},
};

const manifest = await plugin._manifest();

plugin.commands = Object.values(manifest.commands);

plugin.hooks = {};

await execute({
	dir: import.meta.url,
	loadOptions: {
		type: "link",
		root: "toto",
		name: "bruh",
		commands: [LS],
		plugins: new Map([["root-plugin", plugin]]),
	},
	development: true,
});

[mdonnalley]

Take a look at this repo, specifically src/index.ts. It uses esbuild but you can achieve the same result without using it.

You really just need to:

• use the explicit command strategy (docs)
• pass in pjson to the loadOptions so that oclif doesn't need to go looking for the package.json

[charaf-rezrazi-deel]

Thanks, it's a good start for me.

However I have some behaviour I'm not able to understand, maybe you have more context about what's happening:

#!/usr/bin/env -S node --loader ts-node/esm --no-warnings=ExperimentalWarning

import * as fs from "node:fs";
import { Command, Flags, execute, type Interfaces } from "@oclif/core";
import { dirname } from "node:path";
import { fileURLToPath } from "node:url";

class LS extends Command {
  static override description = "List the files in a directory.";
  static override flags = {
    version: Flags.version(),
    help: Flags.help(),
    dir: Flags.string({
      char: "d",
      default: process.cwd(),
    }),
  };

  async run() {
    const { flags } = await this.parse(LS);
    const files = fs.readdirSync(flags.dir);
    for (const f of files) {
      this.log(f);
    }
  }
}

export const COMMANDS: Record<string, Command.Class> = {
  ls: LS,
};

export async function run() {
  console.log({ path: fileURLToPath(import.meta.url) });

  await execute({
    loadOptions: {
      pjson: {
        name: "my-cli",
        version: "1.0.0",
        oclif: {
          commands: {
            strategy: "explicit",
            target: fileURLToPath(import.meta.url),
            identifier: "COMMANDS",
          },
        },
      } as Interfaces.PJSON,
      root: dirname(fileURLToPath(import.meta.url)),
    },
  });
}

// Needs to be anonymous function in order to run from bundled file
// eslint-disable-next-line unicorn/prefer-top-level-await
(async () => {
  await run();
})();

// simple bundle with bun
await Bun.build({
  entrypoints: ["./index.ts"],
  outdir: "./build",
  target: "node",
});

Running in the same workspace as my app: (path is just me doing console.log in index.ts)

➜ node ./build/index.js ls
{ path: '/Users/charaf/dev/oclif-test/build/index.js' }
.gitignore
README.md
build
build.ts
bun.lock
index.ts
node_modules
package.json
tsconfig.json

if I copy the index.js file into a random path:

➜ node ./main.js ls
{ path: '/private/tmp/main.js' }
 ›   Error: command ls not found

[charaf-rezrazi-deel]

what I'm trying to achieve is to bundle a single file (no matter the bundler) by providing oclif with a config which tells it where to find the commands without the need for an package.json file 🙏

[charaf-rezrazi-deel]

nvm, I got debug

~/dev via ⬢ v22.14.0
➜ DEBUG=* node ./index.js ls
{ path: '/Users/charaf/dev/index.js' }
  oclif:main process.execPath: /Users/charaf/.nvm/versions/node/v22.14.0/bin/node +0ms
  oclif:main process.execArgv:  +0ms
  oclif:main process.argv: [
  oclif:main   '/Users/charaf/.nvm/versions/node/v22.14.0/bin/node',
  oclif:main   '/Users/charaf/dev/index.js',
  oclif:main   'ls'
  oclif:main ] +0ms
  oclif:config loading core plugin from /Users/charaf/dev +0ms
  oclif:config:my-cli command discovery options {
  strategy: 'explicit',
  target: '/Users/charaf/dev/index.js',
  identifier: 'COMMANDS'
} +0ms
  oclif:config:ts-path tsconfig: { compilerOptions: {}, 'ts-node': {} } +0ms
  oclif:config:ts-path Determining path for /Users/charaf/dev/index.js +0ms
  oclif:config:ts-path Could not find tsx. Skipping tsx registration for /Users/charaf/dev. +0ms
  oclif:config:ts-path Error: Cannot find module 'tsx/cjs/api'
  oclif:config:ts-path Require stack:
  oclif:config:ts-path - /Users/charaf/dev/index.js
  oclif:config:ts-path     at Function._resolveFilename (node:internal/modules/cjs/loader:1225:15)
  oclif:config:ts-path     at Function.resolve (node:internal/modules/helpers:146:19)
  oclif:config:ts-path     at registerTsx (file:///Users/charaf/dev/index.js:173893:33)
  oclif:config:ts-path     at determinePath (file:///Users/charaf/dev/index.js:173975:13)
  oclif:config:ts-path     at async tsPath (file:///Users/charaf/dev/index.js:174040:14)
  oclif:config:ts-path     at async Plugin.loadCommandsFromTarget (file:///Users/charaf/dev/index.js:183018:26)
  oclif:config:ts-path     at async Plugin.getCommandIdsFromTarget (file:///Users/charaf/dev/index.js:183003:34)
  oclif:config:ts-path     at async Plugin.getCommandIDs (file:///Users/charaf/dev/index.js:182974:17)
  oclif:config:ts-path     at async Plugin._manifest (file:///Users/charaf/dev/index.js:182924:25)
  oclif:config:ts-path     at async Plugin.load (file:///Users/charaf/dev/index.js:182881:23) +0ms
  oclif:config:ts-path registering ts-node at /Users/charaf/dev +8ms
  oclif:config:ts-path Error: Cannot find module 'ts-node'
  oclif:config:ts-path Require stack:
  oclif:config:ts-path - /Users/charaf/dev/index.js
  oclif:config:ts-path     at Function._resolveFilename (node:internal/modules/cjs/loader:1225:15)
  oclif:config:ts-path     at Function.resolve (node:internal/modules/helpers:146:19)
  oclif:config:ts-path     at registerTSNode (file:///Users/charaf/dev/index.js:173913:34)
  oclif:config:ts-path     at determinePath (file:///Users/charaf/dev/index.js:173976:13)
  oclif:config:ts-path     at async tsPath (file:///Users/charaf/dev/index.js:174040:14)
  oclif:config:ts-path     at async Plugin.loadCommandsFromTarget (file:///Users/charaf/dev/index.js:183018:26)
  oclif:config:ts-path     at async Plugin.getCommandIdsFromTarget (file:///Users/charaf/dev/index.js:183003:34)
  oclif:config:ts-path     at async Plugin.getCommandIDs (file:///Users/charaf/dev/index.js:182974:17)
  oclif:config:ts-path     at async Plugin._manifest (file:///Users/charaf/dev/index.js:182924:25)
  oclif:config:ts-path     at async Plugin.load (file:///Users/charaf/dev/index.js:182881:23) +0ms
  oclif:config:my-cli found commands [] +97ms
  oclif:config reading user plugins pjson /Users/charaf/.local/share/my-cli/package.json +98ms
  oclif:config config done +1ms
  oclif:config start init hook +0ms
  oclif:config init hook done +0ms
{ id: 'ls' }
  oclif:config runCommand ls [] +0ms
  oclif:config start command_not_found hook +0ms
  oclif:config command_not_found hook done +0ms
  oclif:config start finally hook +0ms
  oclif:config finally hook done +0ms
 ›   Error: command ls not found
  oclif:error Error: command ls not found
  oclif:error     at Config.runCommand (file://~/dev/index.js:183608:15)
  oclif:error     at async run (file://~/dev/index.js:185231:14)
  oclif:error     at async run (file://~/dev/index.js:185442:3)
  oclif:error     at async file://~/dev/index.js:185460:3 +0ms

Running with bun works 🤔

[charaf-rezrazi-deel]

@mdonnalley I was able to get it to work, by passing it pjson as instructed. I have to rename the file to (name).mjs because I was compiling into ESM.

I have one last question, when I move the script into a blank and random folder, I get this inconvenient warning:

› Warning: Could not find typescript. Please ensure that typescript is a devDependency. Falling back to compiled source.

Is there a way to silence it?

[mdonnalley]

Are you running it development mode? I'm pretty sure the code path that logs that warning is skipped if it detects that you're in a production environment. Take a look at the NODE_ENV you have set in your environment or the options you're passing to execute

https://github.com/oclif/core/blob/main/src/config/ts-path.ts#L305
https://github.com/oclif/core/blob/main/src/util/util.ts#L56
https://github.com/oclif/core/blob/main/src/execute.ts#L55