runspec-node 0.3.0 → 0.7.0

package/src/finder.ts

@@ -1,19 +1,13 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { parse as parseTOML } from 'smol-toml';
 
-export function findConfig(start?: string): { configPath: string; format: 'pyproject' | 'runspec' } {
+export function findConfig(start?: string): { configPath: string } {
   let dir = path.resolve(start ?? process.cwd());
 
   while (true) {
-    const pyproject = path.join(dir, 'pyproject.toml');
-    if (fs.existsSync(pyproject) && hasRunspecSection(pyproject)) {
-      return { configPath: pyproject, format: 'pyproject' };
-    }
-
     const runspecToml = path.join(dir, 'runspec.toml');
     if (fs.existsSync(runspecToml)) {
-      return { configPath: runspecToml, format: 'runspec' };
+      return { configPath: runspecToml };
     }
 
     const parent = path.dirname(dir);
@@ -22,38 +16,6 @@ export function findConfig(start?: string): { configPath: string; format: 'pypro
   }
 
   throw new Error(
-    "No runspec configuration found.\nExpected one of:\n  - pyproject.toml with [tool.runspec] section\n  - runspec.toml\n\nRun 'runspec check' to validate your project setup.",
+    "No runspec configuration found.\nExpected runspec.toml inside your package directory.\n\nRun 'runspec init' to create one.",
   );
 }
-
-export function findScriptName(configPath: string, format: 'pyproject' | 'runspec'): string | undefined {
-  if (format !== 'pyproject') return undefined;
-
-  try {
-    const content = fs.readFileSync(configPath, 'utf-8');
-    const data = parseTOML(content) as Record<string, unknown>;
-    const argv1 = process.argv[1] ?? '';
-    const caller = path.basename(argv1, path.extname(argv1));
-    if (!caller) return undefined;
-
-    const projectScripts = (data as any)?.project?.scripts ?? {};
-    if (caller in projectScripts) return caller;
-
-    const poetryScripts = (data as any)?.tool?.poetry?.scripts ?? {};
-    if (caller in poetryScripts) return caller;
-
-    return caller;
-  } catch {
-    return undefined;
-  }
-}
-
-function hasRunspecSection(pyprojectPath: string): boolean {
-  try {
-    const content = fs.readFileSync(pyprojectPath, 'utf-8');
-    const data = parseTOML(content) as Record<string, unknown>;
-    return 'runspec' in ((data as any)?.tool ?? {});
-  } catch {
-    return false;
-  }
-}

package/src/loader.ts

@@ -2,19 +2,9 @@ import * as fs from 'fs';
 import { parse as parseTOML } from 'smol-toml';
 import type { RawConfig, RawSpec, ScriptSpec, ArgSpec, GroupSpec } from './models';
 
-export function loadRaw(configPath: string, format: 'pyproject' | 'runspec'): RawSpec {
+export function loadRaw(configPath: string): RawSpec {
   const content = fs.readFileSync(configPath, 'utf-8');
-  const data = parseTOML(content) as Record<string, unknown>;
-
-  let raw: Record<string, unknown>;
-  let entryPoints: Record<string, string> = {};
-
-  if (format === 'pyproject') {
-    raw = ((data as any)?.tool?.runspec ?? {}) as Record<string, unknown>;
-    entryPoints = readEntryPoints(data);
-  } else {
-    raw = data;
-  }
+  const raw = parseTOML(content) as Record<string, unknown>;
 
   const runnablesRaw: Record<string, Record<string, unknown>> = {};
   for (const [key, value] of Object.entries(raw)) {
@@ -26,7 +16,6 @@ export function loadRaw(configPath: string, format: 'pyproject' | 'runspec'): Ra
   return {
     config: normaliseConfig((raw['config'] ?? {}) as Record<string, unknown>),
     runnables: normaliseRunnables(runnablesRaw),
-    entryPoints,
   };
 }
 
@@ -111,10 +100,3 @@ function normaliseCommands(raw: Record<string, Record<string, unknown>>): Record
   return Object.fromEntries(Object.entries(raw).map(([name, data]) => [name, normaliseScript(name, data)]));
 }
 
-function readEntryPoints(data: Record<string, unknown>): Record<string, string> {
-  const projectScripts = (data as any)?.project?.scripts;
-  if (projectScripts && typeof projectScripts === 'object') return projectScripts as Record<string, string>;
-  const poetryScripts = (data as any)?.tool?.poetry?.scripts;
-  if (poetryScripts && typeof poetryScripts === 'object') return poetryScripts as Record<string, string>;
-  return {};
-}

package/src/models.ts

@@ -47,7 +47,6 @@ export interface ScriptSpec {
 export interface RawSpec {
   config: RawConfig;
   runnables: Record<string, ScriptSpec>;
-  entryPoints: Record<string, string>;
 }
 
 export interface ParsedArgs {

package/src/parser.ts

@@ -1,5 +1,5 @@
 import * as path from 'path';
-import { findConfig, findScriptName } from './finder';
+import { findConfig } from './finder';
 import { loadRaw } from './loader';
 import { inferScript, effectiveAutonomy } from './inference';
 import { coerce } from './types';
@@ -16,11 +16,11 @@ export interface ParseOptions {
 export function parse(opts: ParseOptions = {}): ParsedArgs {
   const { scriptName, argv: argvOverride, cwd } = opts;
 
-  const { configPath, format } = findConfig(cwd);
-  const raw = loadRaw(configPath, format);
+  const { configPath } = findConfig(cwd);
+  const raw = loadRaw(configPath);
   const config = raw.config;
 
-  const name = scriptName ?? findScriptName(configPath, format) ?? inferFromArgv();
+  const name = scriptName ?? inferFromArgv();
   if (!name) throw new RunSpecError('✗  Could not determine runnable name. Pass scriptName option.');
   if (name === 'config') throw new RunSpecError("✗  'config' is a reserved name in runspec.\n   Rename your runnable.");
 

package/src/serve.ts

@@ -12,39 +12,43 @@ const ERR_PARSE = -32700;
 const ERR_METHOD_NOT_FOUND = -32601;
 const ERR_INVALID_PARAMS = -32602;
 
+const SHELL_EXTS = ['', '.sh', '.ksh', '.bash', '.zsh'];
+
 export function serve(): void {
   let configPath: string;
-  let format: 'pyproject' | 'runspec';
 
   try {
-    ({ configPath, format } = findConfig(process.cwd()));
+    ({ configPath } = findConfig(process.cwd()));
   } catch (e) {
     process.stderr.write(`runspec serve: ${(e as Error).message}\n`);
     process.exit(1);
   }
 
-  const raw = loadRaw(configPath, format);
+  const raw = loadRaw(configPath);
   const config = raw.config;
 
   const tools: Record<string, Record<string, unknown>> = {};
   const argSpecs: Record<string, Record<string, unknown>> = {};
+  const execSpecs: Record<string, { command: string | null }> = {};
+
+  const binDir = path.join(path.dirname(configPath), 'node_modules', '.bin');
 
   for (const [name, runnable] of Object.entries(raw.runnables)) {
     const inferred = inferScript(runnable, config.autonomyDefault);
     tools[name] = buildSchema(name, inferred, 'mcp');
     argSpecs[name] = inferred.args ?? {};
+    execSpecs[name] = { command: findScript(name, binDir) };
   }
 
   const serverName = serverNameFromConfig(config as unknown as Record<string, unknown>);
-  const binDir = path.join(path.dirname(configPath), 'node_modules', '.bin');
 
-  mcpLoop(tools, argSpecs, binDir, serverName);
+  mcpLoop(tools, argSpecs, execSpecs, serverName);
 }
 
 function mcpLoop(
   tools: Record<string, Record<string, unknown>>,
   argSpecs: Record<string, Record<string, unknown>>,
-  binDir: string,
+  execSpecs: Record<string, { command: string | null }>,
   serverName: string,
 ): void {
   const rl = readline.createInterface({ input: process.stdin, crlfDelay: Infinity });
@@ -61,7 +65,7 @@ function mcpLoop(
       return;
     }
 
-    const response = dispatch(request, tools, argSpecs, binDir, serverName);
+    const response = dispatch(request, tools, argSpecs, execSpecs, serverName);
     if (response !== null) writeMsg(response);
   });
 }
@@ -70,7 +74,7 @@ function dispatch(
   request: Record<string, unknown>,
   tools: Record<string, Record<string, unknown>>,
   argSpecs: Record<string, Record<string, unknown>>,
-  binDir: string,
+  execSpecs: Record<string, { command: string | null }>,
   serverName: string,
 ): Record<string, unknown> | null {
   const method = (request['method'] as string) ?? '';
@@ -81,14 +85,14 @@ function dispatch(
   if (method === 'initialize') return handleInitialize(reqId, serverName);
   if (method === 'tools/list') return handleToolsList(reqId, tools);
   if (method === 'tools/call') {
-    return handleToolsCall(reqId, (request['params'] ?? {}) as Record<string, unknown>, tools, argSpecs, binDir);
+    return handleToolsCall(reqId, (request['params'] ?? {}) as Record<string, unknown>, tools, argSpecs, execSpecs);
   }
 
   return { jsonrpc: '2.0', id: reqId, error: { code: ERR_METHOD_NOT_FOUND, message: `Method not found: ${method}` } };
 }
 
 function handleInitialize(reqId: unknown, serverName: string): Record<string, unknown> {
-  const version = '0.3.0';
+  const version = '0.6.0';
   return {
     jsonrpc: '2.0',
     id: reqId,
@@ -109,7 +113,7 @@ function handleToolsCall(
   params: Record<string, unknown>,
   tools: Record<string, Record<string, unknown>>,
   argSpecs: Record<string, Record<string, unknown>>,
-  binDir: string,
+  execSpecs: Record<string, { command: string | null }>,
 ): Record<string, unknown> {
   const name = (params['name'] as string) ?? '';
   const args = (params['arguments'] as Record<string, unknown>) ?? {};
@@ -118,20 +122,22 @@ function handleToolsCall(
     return { jsonrpc: '2.0', id: reqId, error: { code: ERR_INVALID_PARAMS, message: `Unknown tool: ${name}` } };
   }
 
-  const cmd = findScript(name, binDir);
+  const cmd = execSpecs[name]?.command ?? null;
   if (!cmd) {
     return {
       jsonrpc: '2.0',
       id: reqId,
       result: {
-        content: [{ type: 'text', text: `Script not found in ${binDir}: ${name}` }],
+        content: [{ type: 'text', text: `Script '${name}' not found. Place it alongside runspec.toml or in a bin/ subdirectory.` }],
         isError: true,
       },
     };
   }
 
-  const argv = argsToArgv(args, argSpecs[name] ?? {});
-  const env = { ...process.env, RUNSPEC_AGENT: '1' };
+  const toolArgSpecs = argSpecs[name] ?? {};
+  const argv = argsToArgv(args, toolArgSpecs);
+  const runspecEnv = argsToRunspecEnv(args, toolArgSpecs);
+  const env = { ...process.env, RUNSPEC_AGENT: '1', ...runspecEnv };
 
   const result = spawnSync(cmd, argv, { encoding: 'utf-8', env });
 
@@ -159,7 +165,7 @@ function argsToArgv(args: Record<string, unknown>, argSpecs: Record<string, unkn
 
   for (const [argName, spec] of Object.entries(argSpecs)) {
     const s = spec as Record<string, unknown>;
-    let value = args[argName] ?? args[argName.replace(/-/g, '_')];
+    const value = args[argName] ?? args[argName.replace(/-/g, '_')];
     if (value === null || value === undefined) continue;
 
     const flag = `--${argName}`;
@@ -177,11 +183,46 @@ function argsToArgv(args: Record<string, unknown>, argSpecs: Record<string, unkn
   return argv;
 }
 
+function argsToRunspecEnv(args: Record<string, unknown>, argSpecs: Record<string, unknown>): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const [argName, spec] of Object.entries(argSpecs)) {
+    const s = spec as Record<string, unknown>;
+    let value = args[argName] ?? args[argName.replace(/-/g, '_')];
+    if (value === null || value === undefined) value = s['default'];
+    if (value === null || value === undefined) continue;
+
+    const envKey = 'RUNSPEC_' + argName.toUpperCase().replace(/-/g, '_').replace(/\./g, '_');
+    const argType = (s['type'] as string) ?? 'str';
+
+    if (argType === 'flag' || argType === 'bool') {
+      env[envKey] = value ? '1' : '0';
+    } else if (s['multiple'] && Array.isArray(value)) {
+      env[envKey] = (value as unknown[]).map(String).join('\n');
+    } else {
+      env[envKey] = String(value);
+    }
+  }
+
+  return env;
+}
+
 function findScript(name: string, binDir: string): string | null {
-  const candidate = path.join(binDir, name);
-  if (fs.existsSync(candidate)) return candidate;
-  const candidateExe = path.join(binDir, name + '.exe');
-  if (fs.existsSync(candidateExe)) return candidateExe;
+  // 1. node_modules/.bin (Node entry points; also .exe on Windows)
+  for (const ext of [...SHELL_EXTS, '.exe']) {
+    const candidate = path.join(binDir, name + ext);
+    if (fs.existsSync(candidate)) return candidate;
+  }
+
+  // 2. cwd/ and cwd/bin/
+  const cwd = process.cwd();
+  for (const dir of [cwd, path.join(cwd, 'bin')]) {
+    for (const ext of SHELL_EXTS) {
+      const candidate = path.join(dir, name + ext);
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
   return null;
 }
 

package/tests/test_cli_init.test.ts

@@ -0,0 +1,210 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import { execFileSync } from 'child_process';
+
+const CLI = path.resolve(__dirname, '../bin/runspec.js');
+
+function tmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'runspec-init-test-'));
+}
+
+function runCLI(dir: string, cliArgs: string[]): { stdout: string; stderr: string } {
+  try {
+    const stdout = execFileSync('node', [CLI, ...cliArgs], { cwd: dir, encoding: 'utf-8' });
+    return { stdout, stderr: '' };
+  } catch (e: any) {
+    return { stdout: e.stdout ?? '', stderr: e.stderr ?? '' };
+  }
+}
+
+function runInit(dir: string, extraArgs: string[] = []): { stdout: string; stderr: string } {
+  return runCLI(dir, ['init', ...extraArgs]);
+}
+
+// ── init (basic) ──────────────────────────────────────────────────────────────
+
+test('creates runspec.toml and .ts stub by default', () => {
+  const dir = tmpDir();
+  const { stdout } = runInit(dir, ['--name', 'greet']);
+  expect(fs.existsSync(path.join(dir, 'runspec.toml'))).toBe(true);
+  expect(fs.existsSync(path.join(dir, 'greet.ts'))).toBe(true);
+  expect(stdout).toContain('Created runspec.toml');
+  expect(stdout).toContain('Created greet.ts');
+});
+
+test('runspec.toml contains the runnable name', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--name', 'deploy']);
+  const toml = fs.readFileSync(path.join(dir, 'runspec.toml'), 'utf-8');
+  expect(toml).toContain('[deploy]');
+});
+
+test('typescript stub imports parse from runspec-node', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--name', 'greet']);
+  const ts = fs.readFileSync(path.join(dir, 'greet.ts'), 'utf-8');
+  expect(ts).toContain("import { parse } from 'runspec-node'");
+  expect(ts).toContain('function main()');
+  expect(ts).toContain('main();');
+});
+
+test('--lang javascript generates .js stub', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--name', 'greet', '--lang', 'javascript']);
+  expect(fs.existsSync(path.join(dir, 'greet.js'))).toBe(true);
+  const js = fs.readFileSync(path.join(dir, 'greet.js'), 'utf-8');
+  expect(js).toContain("require('runspec-node')");
+  expect(js).toContain('main();');
+});
+
+test('--lang python generates .py stub', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--name', 'greet', '--lang', 'python']);
+  expect(fs.existsSync(path.join(dir, 'greet.py'))).toBe(true);
+  const py = fs.readFileSync(path.join(dir, 'greet.py'), 'utf-8');
+  expect(py).toContain('from runspec import parse');
+  expect(py).toContain('if __name__ == "__main__"');
+});
+
+test('does not overwrite existing stub', () => {
+  const dir = tmpDir();
+  const stubPath = path.join(dir, 'greet.ts');
+  fs.writeFileSync(stubPath, '// existing\n', 'utf-8');
+  const { stdout } = runInit(dir, ['--name', 'greet']);
+  expect(fs.readFileSync(stubPath, 'utf-8')).toBe('// existing\n');
+  expect(stdout).toContain('already exists — skipped');
+});
+
+test('fails if runspec.toml already exists', () => {
+  const dir = tmpDir();
+  fs.writeFileSync(path.join(dir, 'runspec.toml'), '[greet]\n', 'utf-8');
+  const { stdout } = runInit(dir, ['--name', 'greet']);
+  expect(stdout).toContain('already exists');
+  expect(fs.existsSync(path.join(dir, 'greet.ts'))).toBe(false);
+});
+
+test('unknown --lang exits with error', () => {
+  const dir = tmpDir();
+  const { stdout } = runInit(dir, ['--name', 'greet', '--lang', 'ruby']);
+  expect(stdout).toContain('Unknown --lang');
+});
+
+// ── init --example ────────────────────────────────────────────────────────────
+
+test('--example creates runspec.toml with clean and scan', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--example']);
+  const toml = fs.readFileSync(path.join(dir, 'runspec.toml'), 'utf-8');
+  expect(toml).toContain('[clean]');
+  expect(toml).toContain('[scan]');
+});
+
+test('--example creates clean.ts and scan.ts by default', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--example']);
+  expect(fs.existsSync(path.join(dir, 'clean.ts'))).toBe(true);
+  expect(fs.existsSync(path.join(dir, 'scan.ts'))).toBe(true);
+});
+
+test('--example clean stub uses __agent__ check', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--example']);
+  const ts = fs.readFileSync(path.join(dir, 'clean.ts'), 'utf-8');
+  expect(ts).toContain('__agent__');
+  expect(ts).toContain('delete');
+});
+
+test('--example scan stub always outputs JSON', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--example']);
+  const ts = fs.readFileSync(path.join(dir, 'scan.ts'), 'utf-8');
+  expect(ts).toContain('JSON.stringify');
+  expect(ts).not.toContain('format');
+});
+
+test('--example scan toml has no format or delete arg', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--example']);
+  const toml = fs.readFileSync(path.join(dir, 'runspec.toml'), 'utf-8');
+  const scanArgsSection = toml.split('[scan.args]')[1] ?? '';
+  expect(scanArgsSection).not.toContain('format');
+  expect(scanArgsSection).not.toContain('delete');
+});
+
+test('--example scan toml declares output = json', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--example']);
+  const toml = fs.readFileSync(path.join(dir, 'runspec.toml'), 'utf-8');
+  expect(toml).toContain('output      = "json"');
+});
+
+test('--example shows demo prep commands', () => {
+  const dir = tmpDir();
+  const { stdout } = runInit(dir, ['--example']);
+  expect(stdout).toContain('touch -t 202401010000 report.tmp cache.tmp session.tmp');
+  expect(stdout).toContain('scan');
+  expect(stdout).toContain('clean');
+});
+
+test('--example with --name warns name is ignored', () => {
+  const dir = tmpDir();
+  const { stdout } = runInit(dir, ['--example', '--name', 'myapp']);
+  expect(stdout).toContain('--name is ignored');
+});
+
+test('--example --lang javascript creates clean.js and scan.js', () => {
+  const dir = tmpDir();
+  runInit(dir, ['--example', '--lang', 'javascript']);
+  expect(fs.existsSync(path.join(dir, 'clean.js'))).toBe(true);
+  expect(fs.existsSync(path.join(dir, 'scan.js'))).toBe(true);
+});
+
+// ── local command ─────────────────────────────────────────────────────────────
+
+test('local command is recognized', () => {
+  const dir = tmpDir();
+  const { stdout } = runCLI(dir, ['local']);
+  expect(stdout).not.toContain('Unknown command');
+});
+
+test('discover command is no longer available', () => {
+  const dir = tmpDir();
+  const { stdout } = runCLI(dir, ['discover']);
+  expect(stdout).toContain('Unknown command');
+});
+
+test('check command is no longer available', () => {
+  const dir = tmpDir();
+  const { stdout } = runCLI(dir, ['check']);
+  expect(stdout).toContain('Unknown command');
+});
+
+test('emit command is no longer available', () => {
+  const dir = tmpDir();
+  const { stdout } = runCLI(dir, ['emit']);
+  expect(stdout).toContain('Unknown command');
+});
+
+test('jump command is recognized', () => {
+  const dir = tmpDir();
+  const { stdout } = runCLI(dir, ['jump']);
+  expect(stdout).toContain('not yet implemented');
+});
+
+// ── help ──────────────────────────────────────────────────────────────────────
+
+test('top-level help mentions local and jump', () => {
+  const dir = tmpDir();
+  const { stdout } = runCLI(dir, ['--help']);
+  expect(stdout).toContain('local');
+  expect(stdout).toContain('jump');
+  expect(stdout).not.toContain('discover');
+});
+
+test('local --help shows focused help', () => {
+  const dir = tmpDir();
+  const { stdout } = runCLI(dir, ['local', '--help']);
+  expect(stdout).toContain('--format');
+  expect(stdout).toContain('--script');
+});