@orchestraworks/cli 0.3.0 → 0.5.0

package/dist/cli/core/invocation.js

@@ -14,7 +14,7 @@ import { errorCode } from "./errors.js";
 export function addAuthOptions(command) {
     return command
         .option("--profile <name>", "named auth profile to read (default profile if omitted)")
-        .option("--base-url <url>", "platform base URL (overrides PLATFORM_BASE_URL and the stored profile)")
+        .option("--base-url <url>", "platform base URL (overrides ORCHESTRA_BASE_URL, PLATFORM_BASE_URL and the stored profile)")
         .option("--org <id>", "target organization id (overrides ORCHESTRA_ORGANIZATION_ID and the stored profile)");
 }
 /**

package/dist/cli/factory/init.d.ts

@@ -13,7 +13,7 @@ type ModelKeyChoice = Exclude<TemplateChoice, "credits">;
 /** What `--model-key` takes. */
 export declare const MODEL_KEY_CHOICES: readonly ModelKeyChoice[];
 /** Every file the starter writes besides package.json, in the order it prints them. */
-export declare const STARTER_FILES: readonly ["fdk.json", "main.ts", "image/Dockerfile", "image/setup.sh", "agents/bugfix.md", "skills/codebase/SKILL.md"];
+export declare const STARTER_FILES: readonly ["fdk.json", "tsconfig.json", "main.ts", "image/Dockerfile", "image/setup.sh", "agents/bugfix.md", "skills/codebase/SKILL.md"];
 /** The starter plain `orchestra fdk init` writes, and the only one `--repository` and `--model-key` fill in. */
 export declare const DEFAULT_TEMPLATE = "bug-fix";
 /** The starters `--template` offers by name. Each is a folder under templates/ that brings its own package.json. */

package/dist/cli/factory/init.js

@@ -13,6 +13,7 @@ export const MODEL_KEY_CHOICES = TEMPLATE_CHOICES.filter((choice) => choice !==
 /** Every file the starter writes besides package.json, in the order it prints them. */
 export const STARTER_FILES = [
     "fdk.json",
+    "tsconfig.json",
     "main.ts",
     "image/Dockerfile",
     "image/setup.sh",
@@ -27,8 +28,12 @@ const TEMPLATES_DIR = "templates";
 const TEMPLATE_DIR = join(TEMPLATES_DIR, DEFAULT_TEMPLATE);
 /** The one template file `init` fills in; every other file is copied as it is. */
 const FILLED_FILE = "main.ts";
+/** What runs main.ts and checks its types; each is added at the range the kit itself is built with. */
+const STARTER_DEV_PACKAGES = ["tsx", "typescript", "@types/node"];
+/** The script the starter adds when package.json has none of that name. */
+const TYPECHECK_SCRIPT = { name: "typecheck", command: "tsc -p tsconfig.json" };
 /** Any other package in package.json means the folder is a codebase rather than a new folder beside one. */
-const PACKAGES_ALLOWED = new Set([KIT_PACKAGE_NAME, "tsx"]);
+const PACKAGES_ALLOWED = new Set([KIT_PACKAGE_NAME, ...STARTER_DEV_PACKAGES]);
 const DEPENDENCY_FIELDS = ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"];
 /** Leaves room for the longest construct path the template declares, so every derived slug stays within 60. */
 const FACTORY_NAME_MAX = 30;
@@ -90,15 +95,24 @@ export async function initCommand(options, io = defaultIo) {
         };
     });
     const record = manifest.kind === "object" ? manifest.record : {};
-    const addsTsx = !listsPackage(record, "tsx");
-    const devDependencies = { ...dependencyMap(record, "devDependencies"), tsx: kitTsxRange(packageRoot) };
-    const merged = { ...record, type: "module", ...(addsTsx ? { devDependencies } : {}) };
+    const added = STARTER_DEV_PACKAGES.filter((name) => !listsPackage(record, name));
+    const ranges = kitDevRanges(packageRoot, added);
+    const devDependencies = { ...dependencyMap(record, "devDependencies"), ...ranges };
+    // A `scripts` that is not an object is left as it is rather than replaced.
+    const addsTypecheck = record.scripts === undefined || (isRecord(record.scripts) && record.scripts[TYPECHECK_SCRIPT.name] === undefined);
+    const scripts = dependencyMap(record, "scripts");
+    const merged = {
+        ...record,
+        type: "module",
+        ...(addsTypecheck ? { scripts: { ...scripts, [TYPECHECK_SCRIPT.name]: TYPECHECK_SCRIPT.command } } : {}),
+        ...(added.length > 0 ? { devDependencies } : {}),
+    };
     writeFileSync(manifestPath, `${JSON.stringify(merged, null, 2)}\n`);
     for (const { path, text } of contents) {
         mkdirSync(dirname(join(dir, path)), { recursive: true });
         writeFileSync(join(dir, path), text);
     }
-    printNextSteps(io, { repository: repository.full, factoryName, choice, dir, addsTsx });
+    printNextSteps(io, { repository: repository.full, factoryName, choice, dir, added, addsTypecheck });
 }
 /** The starters this kit carries: one folder each under templates/. */
 export function availableTemplates(packageRoot = runningPackageRoot()) {
@@ -325,14 +339,19 @@ function dependencyMap(record, field) {
     const value = record[field];
     return isRecord(value) ? value : {};
 }
-/** The tsx range the kit itself is tested with, so the starter runs on the tsx the kit was proven on. */
-function kitTsxRange(packageRoot) {
+/** The ranges the kit itself is built and tested with, so the starter runs and type-checks on what the kit was proven on. */
+function kitDevRanges(packageRoot, names) {
     const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-    const range = isRecord(manifest) ? dependencyMap(manifest, "devDependencies").tsx : undefined;
-    if (typeof range !== "string") {
-        throw new Error("this orchestra install names no tsx version to add. Reinstall the kit, then run orchestra fdk init again.");
+    const kitDev = isRecord(manifest) ? dependencyMap(manifest, "devDependencies") : {};
+    const ranges = {};
+    for (const name of names) {
+        const range = kitDev[name];
+        if (typeof range !== "string") {
+            throw new Error(`this orchestra install names no ${name} version to add. Reinstall the kit, then run orchestra fdk init again.`);
+        }
+        ranges[name] = range;
     }
-    return range;
+    return ranges;
 }
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -341,12 +360,17 @@ function printNextSteps(io, written) {
     const inputs = [...SHELL_INPUTS, ...(written.choice === "credits" ? [] : [MODEL_KEY_INPUTS[written.choice]])];
     const width = Math.max(...inputs.map(([name]) => name.length)) + 2;
     io.out(`Wrote a bug-fix factory named '${written.factoryName}' for ${written.repository} into ${written.dir}:`);
-    io.out(`  package.json (set "type": "module"${written.addsTsx ? ", added tsx to devDependencies" : ""})`);
+    const changes = [
+        `set "type": "module"`,
+        ...(written.addsTypecheck ? [`added the ${TYPECHECK_SCRIPT.name} script`] : []),
+        ...(written.added.length > 0 ? [`added ${listed(written.added)} to devDependencies`] : []),
+    ];
+    io.out(`  package.json (${changes.join(", ")})`);
     for (const path of STARTER_FILES)
         io.out(`  ${path}`);
     io.out("");
     io.out("Next, in this folder:");
-    io.out("  1. npm install");
+    io.out("  1. npm install, then npm run typecheck");
     io.out("  2. In the shell that runs orchestra, set these values. The platform's team hands them over until image");
     io.out("     hosting exists:");
     for (const [name, what] of inputs)
@@ -356,3 +380,7 @@ function printNextSteps(io, written) {
     io.out("  3. npx orchestra fdk diff");
     io.out("  4. npx orchestra fdk apply, then open the GitHub App install link it prints. It waits for the install.");
 }
+/** `a`, `a and b`, or `a, b and c`. */
+function listed(names) {
+    return names.length === 1 ? names[0] : `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}

package/dist/cli/skill.js

@@ -21,8 +21,17 @@ const LINKABLE_HARNESSES = ["claude", "codex"];
 const HARNESS_LABEL = { claude: "Claude Code", codex: "Codex" };
 const HARNESS_VALUES = ["claude", "codex", "both", "other"];
 const SCOPE_VALUES = ["user", "project"];
-/** How a person keeps the linked skills current: the global install is updated in place. */
-const UPDATE_COMMAND = `npm update -g ${KIT_INSTALL_SPEC}`;
+/**
+ * How a person keeps the linked skills current: the install the links point into is updated in place, so the
+ * command matches where the running package sits. A checkout outside both reads as global, the common case.
+ */
+function updateCommand(running) {
+    return running.kind === "project" ? `npm update ${KIT_INSTALL_SPEC}` : `npm update -g ${KIT_INSTALL_SPEC}`;
+}
+/** The folder whose `node_modules` holds a project install: `<folder>/node_modules/@orchestraworks/cli`. */
+function installFolder(packageRoot) {
+    return dirname(dirname(dirname(packageRoot)));
+}
 export async function skillInstallCommand(options, deps = {}) {
     const io = deps.io ?? defaultIo;
     const env = deps.env ?? process.env;
@@ -90,14 +99,18 @@ export async function skillInstallCommand(options, deps = {}) {
         return;
     }
     io.out("");
-    printSkillFiles(io, running.packageRoot);
+    printSkillFiles(io, running);
 }
 /** The step after the links: a harness loads a new skill only at its next start, so read them now. */
-function printSkillFiles(io, packageRoot) {
+function printSkillFiles(io, running) {
     io.out("Read each skill now; your harness loads new skills only at its next start:");
     for (const skill of KIT_SKILLS)
-        io.out(`  ${skillFileIn(packageRoot, skill)}`);
-    io.out(`\`${UPDATE_COMMAND}\` keeps them current.`);
+        io.out(`  ${skillFileIn(running.packageRoot, skill)}`);
+    io.out("The kit may be installed globally or in the factory folder.");
+    io.out(running.kind === "project"
+        ? `This one is installed in ${installFolder(running.packageRoot)}, so \`${updateCommand(running)}\`, run in ` +
+            `that folder, keeps them current.`
+        : `This one is installed globally, so \`${updateCommand(running)}\` keeps them current.`);
 }
 function parseChoice(raw, allowed, flag) {
     if (raw === undefined) {
@@ -194,7 +207,7 @@ function printPointingInstructions(io, running, anchors, fs) {
     for (const file of skillFiles)
         io.out(`  ${file}`);
     io.out("");
-    io.out(`Point your harness at each directory (a link keeps it current across '${UPDATE_COMMAND}'):`);
+    io.out(`Point your harness at each directory (a link keeps it current across '${updateCommand(running)}'):`);
     for (const harness of LINKABLE_HARNESSES) {
         // The project leg prints the RELATIVE target the command itself would write, so a hand-made link
         // travels with the repo exactly like an installed one. Nothing recomputes after this line — the