runspec-node 0.3.0

package/dist/validator.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateArgs = validateArgs;
+exports.validateGroups = validateGroups;
+exports.raiseIfErrors = raiseIfErrors;
+const errors_1 = require("./errors");
+function validateArgs(parsedValues, argSpecs) {
+    const errors = [];
+    for (const [name, spec] of Object.entries(argSpecs)) {
+        const value = parsedValues[name];
+        const missing = value === null || value === undefined;
+        if (spec.required && missing) {
+            errors.push((0, errors_1.formatMissingRequired)(name, spec));
+            continue;
+        }
+        if (!missing && spec.deprecated) {
+            process.stderr.write((0, errors_1.formatDeprecated)(name, spec.deprecated) + '\n');
+        }
+    }
+    return errors;
+}
+function validateGroups(parsedValues, groupSpecs) {
+    const errors = [];
+    for (const [groupName, group] of Object.entries(groupSpecs)) {
+        const groupArgs = group.args ?? [];
+        const provided = groupArgs.filter((a) => parsedValues[a] !== null && parsedValues[a] !== undefined);
+        if (group.exclusive && provided.length > 1) {
+            errors.push((0, errors_1.formatGroupExclusive)(groupName, provided));
+        }
+        else if (group.inclusive && provided.length > 0 && provided.length < groupArgs.length) {
+            errors.push((0, errors_1.formatGroupInclusive)(groupName, groupArgs.filter((a) => !provided.includes(a))));
+        }
+        else if (group.atLeastOne && provided.length === 0) {
+            errors.push((0, errors_1.formatGroupAtLeastOne)(groupName, groupArgs));
+        }
+        else if (group.exactlyOne && provided.length !== 1) {
+            errors.push((0, errors_1.formatGroupExactlyOne)(groupName, groupArgs, provided));
+        }
+        else if (group.condition) {
+            const condVal = parsedValues[group.condition];
+            if (condVal !== null && condVal !== undefined) {
+                const requires = group.requires ?? [];
+                const missing = requires.filter((a) => parsedValues[a] === null || parsedValues[a] === undefined);
+                if (missing.length > 0)
+                    errors.push((0, errors_1.formatGroupInclusive)(groupName, missing));
+            }
+        }
+    }
+    return errors;
+}
+function raiseIfErrors(errorMessages) {
+    if (errorMessages.length > 0) {
+        throw new errors_1.RunSpecError(errorMessages.join('\n\n'));
+    }
+}
+//# sourceMappingURL=validator.js.map

package/dist/validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validator.js","sourceRoot":"","sources":["../src/validator.ts"],"names":[],"mappings":"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"}

package/jest.config.js

@@ -0,0 +1,8 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  roots: ['<rootDir>/tests'],
+  testMatch: ['**/*.test.ts'],
+  collectCoverageFrom: ['src/**/*.ts'],
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "runspec-node",
+  "version": "0.3.0",
+  "description": "Node/TypeScript language pack for runspec",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "runspec": "./bin/runspec.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "jest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "keywords": ["runspec", "cli", "arguments", "agents", "mcp"],
+  "author": "Jason Finestone",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JasonFinestone/runspec"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.0.0",
+    "@types/node": "^20.0.0",
+    "jest": "^29.0.0",
+    "ts-jest": "^29.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "smol-toml": "^1.0.0"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,378 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { findConfig } from './finder';
+import { loadRaw } from './loader';
+import { inferScript } from './inference';
+import type { ScriptSpec, ArgSpec } from './models';
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+export function main(): void {
+  const args = process.argv.slice(2);
+
+  if (!args.length || args[0] === '-h' || args[0] === '--help') {
+    printHelp();
+    return;
+  }
+
+  const command = args[0];
+  const rest = args.slice(1);
+
+  const commands: Record<string, (args: string[]) => void> = {
+    init: cmdInit,
+    discover: cmdDiscover,
+    check: cmdCheck,
+    emit: cmdEmit,
+    serve: cmdServe,
+  };
+
+  if (!(command in commands)) {
+    console.log(`✗  Unknown command: ${command}`);
+    console.log(`   Available commands: ${Object.keys(commands).join(', ')}`);
+    process.exit(1);
+  }
+
+  commands[command](rest);
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+function cmdInit(args: string[]): void {
+  const nameFlag = getFlag(args, '--name');
+  const fileFlag = getFlag(args, '--file');
+
+  const cwd = process.cwd();
+  const runnableName = nameFlag ?? sanitizeName(path.basename(cwd));
+
+  const pyproject = path.join(cwd, 'pyproject.toml');
+  const runspecToml = path.join(cwd, 'runspec.toml');
+
+  if (fileFlag === 'runspec') {
+    initRunspecToml(runspecToml, runnableName);
+  } else if (fileFlag === 'pyproject' || fs.existsSync(pyproject)) {
+    initPyproject(pyproject, runnableName);
+  } else {
+    initRunspecToml(runspecToml, runnableName);
+  }
+}
+
+function cmdDiscover(args: string[]): void {
+  const fmt = getFlag(args, '--format') ?? 'text';
+
+  const discovered = discoverLocal();
+
+  if (!discovered.length) {
+    console.log('No runspec-aware runnables found in this environment.');
+    console.log('Add a [tool.runspec.yourname] section to pyproject.toml or create runspec.toml');
+    return;
+  }
+
+  if (fmt === 'text') {
+    printDiscoverText(discovered);
+  } else if (fmt === 'json') {
+    console.log(JSON.stringify(discovered, null, 2));
+  } else if (['mcp', 'openai', 'anthropic'].includes(fmt)) {
+    console.log(JSON.stringify(emitAll(discovered, fmt), null, 2));
+  } else {
+    console.log(`✗  Unknown format: ${fmt}`);
+    console.log('   Available formats: text, json, mcp, openai, anthropic');
+    process.exit(1);
+  }
+}
+
+function cmdCheck(args: string[]): void {
+  let configPath: string;
+  let format: 'pyproject' | 'runspec';
+
+  try {
+    ({ configPath, format } = findConfig(process.cwd()));
+  } catch (e) {
+    console.log((e as Error).message);
+    process.exit(1);
+  }
+
+  const raw = loadRaw(configPath, format);
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const ok: string[] = [];
+
+  ok.push(`Config found: ${configPath}`);
+
+  if (format === 'pyproject') {
+    const eps = raw.entryPoints;
+    if (Object.keys(eps).length > 0) {
+      ok.push(`[project.scripts] found — ${Object.keys(eps).length} entry point(s)`);
+    } else {
+      warnings.push('No [project.scripts] found — agents may not discover runnables automatically\n  Add entry points to pyproject.toml or use runspec.toml');
+    }
+  }
+
+  if ('config' in raw.runnables) {
+    errors.push("'config' is a reserved name — rename your runnable to something else");
+  }
+
+  for (const [name, runnable] of Object.entries(raw.runnables)) {
+    if (!runnable.description) {
+      warnings.push(`'${name}' has no description — agents won't know what it does`);
+    } else {
+      ok.push(`'${name}' — description present`);
+    }
+
+    if (!runnable.autonomy) {
+      warnings.push(`'${name}' autonomy not declared — will default to '${raw.config.autonomyDefault}'`);
+    } else {
+      ok.push(`'${name}' — autonomy: ${runnable.autonomy}`);
+    }
+
+    for (const [argName, arg] of Object.entries(runnable.args ?? {})) {
+      if (!arg.description && arg.required) {
+        warnings.push(`'${name}.${argName}' is required but has no description`);
+      }
+    }
+  }
+
+  for (const msg of ok) console.log(`  ✓  ${msg}`);
+  for (const msg of warnings) console.log(`  ℹ  ${msg}`);
+  for (const msg of errors) console.log(`  ✗  ${msg}`);
+
+  if (errors.length) process.exit(1);
+  else if (!warnings.length) console.log('\n  All checks passed.');
+}
+
+function cmdEmit(args: string[]): void {
+  const scriptName = getFlag(args, '--script');
+  const fmt = getFlag(args, '--format') ?? 'mcp';
+
+  let configPath: string;
+  let format: 'pyproject' | 'runspec';
+
+  try {
+    ({ configPath, format } = findConfig(process.cwd()));
+  } catch (e) {
+    console.log((e as Error).message);
+    process.exit(1);
+  }
+
+  const raw = loadRaw(configPath, format);
+  const config = raw.config;
+
+  let runnables = raw.runnables;
+  if (scriptName) {
+    if (!(scriptName in runnables)) {
+      console.log(`✗  Runnable '${scriptName}' not found`);
+      process.exit(1);
+    }
+    runnables = { [scriptName]: runnables[scriptName] };
+  }
+
+  const schema: Record<string, unknown> = {};
+  for (const [name, runnable] of Object.entries(runnables)) {
+    const inferred = inferScript(runnable, config.autonomyDefault);
+    schema[name] = buildSchema(name, inferred, fmt);
+  }
+
+  const output = fmt === 'mcp' ? { tools: Object.values(schema) } : schema;
+  console.log(JSON.stringify(output, null, 2));
+}
+
+function cmdServe(_args: string[]): void {
+  const { serve } = require('./serve') as { serve: () => void };
+  serve();
+}
+
+// ── Schema builder ────────────────────────────────────────────────────────────
+
+export function buildSchema(name: string, script: ScriptSpec, fmt: string): Record<string, unknown> {
+  const properties: Record<string, unknown> = {};
+  const requiredArgs: string[] = [];
+
+  for (const [argName, arg] of Object.entries(script.args ?? {})) {
+    properties[argName] = argToJsonSchema(arg);
+    if (arg.required) requiredArgs.push(argName);
+  }
+
+  const schema: Record<string, unknown> = {
+    name,
+    description: script.description ?? '',
+    'x-autonomy': script.autonomy ?? 'confirm',
+    'x-output': script.output ?? 'text',
+    inputSchema: { type: 'object', properties },
+  };
+
+  if (requiredArgs.length) (schema['inputSchema'] as Record<string, unknown>)['required'] = requiredArgs;
+  if (script.autonomyReason) schema['x-autonomy-reason'] = script.autonomyReason;
+
+  return schema;
+}
+
+function argToJsonSchema(arg: ArgSpec): Record<string, unknown> {
+  const typeMap: Record<string, string> = {
+    str: 'string',
+    int: 'integer',
+    float: 'number',
+    bool: 'boolean',
+    flag: 'boolean',
+    path: 'string',
+    choice: 'string',
+  };
+
+  let prop: Record<string, unknown> = { type: typeMap[arg.type ?? 'str'] ?? 'string' };
+  if (arg.description) prop['description'] = arg.description;
+  if (arg.default !== undefined && arg.default !== null) prop['default'] = arg.default;
+  if (arg.options) prop['enum'] = arg.options;
+  if (arg.range) {
+    prop['minimum'] = arg.range[0];
+    prop['maximum'] = arg.range[1];
+  }
+  if (arg.multiple) prop = { type: 'array', items: prop };
+
+  return prop;
+}
+
+// ── Discovery ─────────────────────────────────────────────────────────────────
+
+function discoverLocal(): Array<{ source: string; runnable: string; spec: ScriptSpec }> {
+  try {
+    const { configPath, format } = findConfig(process.cwd());
+    const raw = loadRaw(configPath, format);
+    return Object.entries(raw.runnables).map(([name, spec]) => ({ source: configPath, runnable: name, spec }));
+  } catch {
+    return [];
+  }
+}
+
+function emitAll(discovered: Array<{ source: string; runnable: string; spec: ScriptSpec }>, fmt: string): Record<string, unknown> {
+  const tools = discovered.map((item) => buildSchema(item.runnable, item.spec, fmt));
+  if (fmt === 'mcp') return { tools };
+  return Object.fromEntries(tools.map((t) => [t['name'], t]));
+}
+
+function printDiscoverText(discovered: Array<{ source: string; runnable: string; spec: ScriptSpec }>): void {
+  const bySource: Record<string, string[]> = {};
+  for (const item of discovered) {
+    (bySource[item.source] ??= []).push(item.runnable);
+  }
+  console.log(`Found ${discovered.length} runspec-aware runnable(s):\n`);
+  for (const [source, runnables] of Object.entries(bySource)) {
+    console.log(`  ${source}`);
+    for (const r of runnables) console.log(`    • ${r}`);
+  }
+  console.log();
+  console.log("Run 'runspec discover --format mcp' to emit MCP tool schemas.");
+}
+
+// ── Init helpers ──────────────────────────────────────────────────────────────
+
+function sanitizeName(raw: string): string {
+  const s = raw.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+  return s || 'myscript';
+}
+
+function initPyproject(filePath: string, name: string): void {
+  if (fs.existsSync(filePath)) {
+    const original = fs.readFileSync(filePath, 'utf-8');
+    let data: Record<string, unknown>;
+    try {
+      const { parse } = require('smol-toml') as { parse: (s: string) => unknown };
+      data = parse(original) as Record<string, unknown>;
+    } catch (e) {
+      console.log(`✗  Could not read ${path.basename(filePath)}: ${(e as Error).message}`);
+      process.exit(1);
+    }
+
+    if ('runspec' in ((data as any)?.tool ?? {})) {
+      const existing = Object.keys((data as any).tool.runspec).filter(
+        (k) => k !== 'config' && typeof (data as any).tool.runspec[k] === 'object',
+      );
+      console.log(`✗  ${path.basename(filePath)} already has [tool.runspec] — already initialized`);
+      if (existing.length) console.log(`   Existing runnables: ${existing.join(', ')}`);
+      process.exit(1);
+    }
+
+    const content = original.trimEnd() + '\n\n' + pyprojectBlock(name);
+    writeAndVerify(filePath, content, original);
+    console.log(`  ✓  Updated ${path.basename(filePath)} with [${name}] runnable`);
+  } else {
+    const content = pyprojectBlock(name);
+    writeAndVerify(filePath, content, null);
+    console.log(`  ✓  Created ${path.basename(filePath)} with [${name}] runnable`);
+  }
+  console.log("     Run 'runspec check' to validate.");
+}
+
+function initRunspecToml(filePath: string, name: string): void {
+  if (fs.existsSync(filePath)) {
+    console.log(`✗  ${path.basename(filePath)} already exists — already initialized`);
+    console.log(`   Edit ${path.basename(filePath)} directly to add more runnables.`);
+    process.exit(1);
+  }
+  writeAndVerify(filePath, runspecTomlBlock(name), null);
+  console.log(`  ✓  Created ${path.basename(filePath)} with [${name}] runnable`);
+  console.log("     Run 'runspec check' to validate.");
+}
+
+function pyprojectBlock(name: string): string {
+  return `[tool.runspec.${name}]\ndescription = "Describe what ${name} does"\nautonomy    = "confirm"\n\n[tool.runspec.${name}.args]\n# example = {type = "str", description = "An example argument"}\n`;
+}
+
+function runspecTomlBlock(name: string): string {
+  return `[${name}]\ndescription = "Describe what ${name} does"\nautonomy    = "confirm"\n\n[${name}.args]\n# example = {type = "str", description = "An example argument"}\n`;
+}
+
+function writeAndVerify(filePath: string, content: string, original: string | null): void {
+  fs.writeFileSync(filePath, content, 'utf-8');
+  try {
+    const { parse } = require('smol-toml') as { parse: (s: string) => unknown };
+    parse(content);
+  } catch (e) {
+    if (original !== null) fs.writeFileSync(filePath, original, 'utf-8');
+    else fs.unlinkSync(filePath);
+    console.log('✗  Generated invalid TOML — this is a bug, please report it');
+    console.log(`   ${(e as Error).message}`);
+    process.exit(1);
+  }
+}
+
+// ── Arg parser helper ─────────────────────────────────────────────────────────
+
+function getFlag(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx !== -1 && idx + 1 < args.length) return args[idx + 1];
+  return undefined;
+}
+
+// ── Help ──────────────────────────────────────────────────────────────────────
+
+function printHelp(): void {
+  console.log(`runspec — interface specification for anything runnable
+
+Usage:
+  runspec <command> [options]
+
+Commands:
+  init        Create or update pyproject.toml or runspec.toml with a scaffold
+  discover    Find all runspec-aware runnables in this environment
+  check       Validate this project's runspec setup
+  emit        Emit tool schemas for agent frameworks
+  serve       Start the MCP stdio server for this environment
+
+Options for init:
+  --name      Runnable name (default: current directory name)
+  --file      Target file: pyproject or runspec (auto-detected if omitted)
+
+Options for discover:
+  --format    Output format: text (default), json, mcp, openai, anthropic
+
+Options for emit:
+  --script    Runnable name to emit (all runnables if omitted)
+  --format    Output format: mcp (default), openai, anthropic
+
+Examples:
+  runspec init
+  runspec init --name myapp
+  runspec discover
+  runspec discover --format mcp
+  runspec check
+  runspec emit --script deploy --format mcp
+  runspec emit --format openai`);
+}

package/src/errors.ts

@@ -0,0 +1,126 @@
+export class RunSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'RunSpecError';
+  }
+}
+
+export class MissingRequiredArg extends RunSpecError {}
+export class InvalidChoice extends RunSpecError {}
+export class OutOfRange extends RunSpecError {}
+export class UnknownArg extends RunSpecError {}
+export class GroupViolation extends RunSpecError {}
+export class AutonomyViolation extends RunSpecError {}
+
+export function formatMissingRequired(name: string, spec: Record<string, unknown>): string {
+  const lines = [
+    `✗  Missing required argument: --${name}`,
+    `   Type: ${spec['type'] ?? 'str'}`,
+  ];
+  if (spec['description']) lines.push(`   Description: ${spec['description']}`);
+  if (spec['env']) lines.push(`   Tip: set environment variable ${spec['env']} as an alternative`);
+  return lines.join('\n');
+}
+
+export function formatInvalidChoice(value: string, options: string[], name: string): string {
+  const lines = [
+    `✗  Invalid value for --${name}: ${JSON.stringify(value)}`,
+    `   Expected one of: ${options.join(', ')}`,
+    `   Got: ${JSON.stringify(value)}`,
+  ];
+  const s = suggest(value, options);
+  if (s) lines.push(`\n   Did you mean: ${s}?`);
+  return lines.join('\n');
+}
+
+export function formatOutOfRange(value: number, range: [number, number], name: string): string {
+  return [
+    `✗  Value out of range for --${name}: ${value}`,
+    `   Expected: between ${range[0]} and ${range[1]}`,
+    `   Got: ${value}`,
+  ].join('\n');
+}
+
+export function formatUnknownArg(name: string, knownArgs: string[]): string {
+  const lines = [
+    `✗  Unknown argument: --${name}`,
+    `   Known arguments: ${[...knownArgs].sort().map((a) => `--${a}`).join(', ')}`,
+  ];
+  const s = suggest(name, knownArgs);
+  if (s) lines.push(`\n   Did you mean: --${s}?`);
+  return lines.join('\n');
+}
+
+export function formatGroupExclusive(groupName: string, provided: string[]): string {
+  return [
+    `✗  Conflicting arguments in group '${groupName}'`,
+    `   --${provided[0]} and --${provided[1]} cannot be used together`,
+    `   Choose one or the other`,
+  ].join('\n');
+}
+
+export function formatGroupInclusive(groupName: string, missing: string[]): string {
+  return [
+    `✗  Incomplete argument group '${groupName}'`,
+    `   Providing one of these args requires all of them`,
+    `   Also provide: ${missing.map((m) => `--${m}`).join(' and ')}`,
+  ].join('\n');
+}
+
+export function formatGroupAtLeastOne(groupName: string, args: string[]): string {
+  return [
+    `✗  Group '${groupName}' requires at least one argument`,
+    `   Provide at least one of: ${args.map((a) => `--${a}`).join(', ')}`,
+  ].join('\n');
+}
+
+export function formatGroupExactlyOne(groupName: string, args: string[], provided: string[]): string {
+  if (!provided.length) {
+    return [
+      `✗  Group '${groupName}' requires exactly one argument`,
+      `   Provide exactly one of: ${args.map((a) => `--${a}`).join(', ')}`,
+    ].join('\n');
+  }
+  return [
+    `✗  Group '${groupName}' requires exactly one argument`,
+    `   Got ${provided.length}: ${provided.map((a) => `--${a}`).join(', ')}`,
+    `   Provide exactly one of: ${args.map((a) => `--${a}`).join(', ')}`,
+  ].join('\n');
+}
+
+export function formatDeprecated(name: string, message: string): string {
+  return `⚠  --${name} is deprecated: ${message}`;
+}
+
+function suggest(value: string, candidates: string[]): string | undefined {
+  let best: string | undefined;
+  let bestScore = 0;
+  for (const c of candidates) {
+    const score = diceSimilarity(value, c);
+    if (score > bestScore && score >= 0.6) {
+      bestScore = score;
+      best = c;
+    }
+  }
+  return best;
+}
+
+function diceSimilarity(a: string, b: string): number {
+  if (a === b) return 1;
+  if (a.length < 2 || b.length < 2) return 0;
+  const bigrams = new Map<string, number>();
+  for (let i = 0; i < a.length - 1; i++) {
+    const bg = a.slice(i, i + 2);
+    bigrams.set(bg, (bigrams.get(bg) ?? 0) + 1);
+  }
+  let intersect = 0;
+  for (let i = 0; i < b.length - 1; i++) {
+    const bg = b.slice(i, i + 2);
+    const count = bigrams.get(bg) ?? 0;
+    if (count > 0) {
+      bigrams.set(bg, count - 1);
+      intersect++;
+    }
+  }
+  return (2 * intersect) / (a.length + b.length - 2);
+}

package/src/finder.ts

@@ -0,0 +1,59 @@
+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' } {
+  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' };
+    }
+
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  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.",
+  );
+}
+
+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/index.ts

@@ -0,0 +1,6 @@
+export { parse, loadSpec } from './parser';
+export { registerType, listTypes } from './types';
+export { RunSpecError, MissingRequiredArg, InvalidChoice, OutOfRange, UnknownArg, GroupViolation, AutonomyViolation } from './errors';
+export { findConfig } from './finder';
+export { loadRaw } from './loader';
+export type { ParsedArgs, ScriptSpec, ArgSpec, GroupSpec, RawSpec, RawConfig } from './models';