@orchestraworks/cli 0.5.0 → 0.5.1

package/README.md

@@ -2,6 +2,17 @@
 
 The `orchestra` command line and the FDK library: write your software factory in TypeScript and apply it to the Orchestra platform.
 
+## For coding agents
+
+Do these steps in order.
+
+1. Install the CLI: `npm install -g @orchestraworks/cli && orchestra --help`. Or run `npm install @orchestraworks/cli` in the factory folder. The help ends with the paths of the two skills on this machine.
+2. Read both skills. Read [skills/orchestra/SKILL.md](https://unpkg.com/@orchestraworks/cli/skills/orchestra/SKILL.md) to learn how to use the orchestra CLI, and [skills/orchestra-fdk/SKILL.md](https://unpkg.com/@orchestraworks/cli/skills/orchestra-fdk/SKILL.md) to set up a factory.
+3. To link both skills into your harness, run `orchestra skills install --harness claude --scope project` (or `--harness codex`) in the factory folder.
+4. Follow the `orchestra-fdk` skill. It tells you what to ask the developer and which commands to run.
+
+The full guide to every construct, secrets, connections and troubleshooting is [docs/REFERENCE.md](https://unpkg.com/@orchestraworks/cli/docs/REFERENCE.md). `orchestra <command> --help` gives the flags of one command.
+
 ## Install
 
 - **Node ≥ 22** is required.
@@ -9,13 +20,15 @@ The `orchestra` command line and the FDK library: write your software factory in
 ```bash
 npm install -g @orchestraworks/cli         # the CLI, on your path as `orchestra`
 npm install @orchestraworks/cli            # the current release
-npm install @orchestraworks/cli@0.5.0      # this exact release
+npm install @orchestraworks/cli@0.5.1      # this exact release
 ```
 
 Then `import { Factory, Agent, … } from "@orchestraworks/cli"` normally — the package `exports` entry resolves
 to the built `dist/` that ships inside this package, so there is nothing to build. Run the CLI
 as `orchestra …` after the global install, or as `npx orchestra …` from a folder that installed the package.
 
+`npm update -g @orchestraworks/cli` keeps a global install and both skills current. For a folder install, run `npm update @orchestraworks/cli` in that folder.
+
 ## Quick start
 
 Make a new, empty folder and go into it. Run every command from the **factory directory**: this folder, which holds `fdk.json` after `fdk init`.
@@ -30,15 +43,6 @@ orchestra fdk apply                                      # make the platform mat
 
 Before `fdk apply`, read the `README.md` that `fdk init` writes. It names the values to set.
 
-## For coding agents
-
-- `skills/orchestra/SKILL.md`: the platform's ideas, how the CLI works, and what it cannot do yet.
-- `skills/orchestra-fdk/SKILL.md`: how to build and apply a factory for an existing codebase.
-- `orchestra --help` lists every command. `orchestra <command> --help` gives its flags.
-- [docs/REFERENCE.md](docs/REFERENCE.md): the full guide to every construct, secrets, connections and troubleshooting.
-
-`orchestra skills install` links both skills into your coding harness. Read the `SKILL.md` in each skill folder the command prints. The CLI may be installed globally or in your factory folder. `npm update -g @orchestraworks/cli` keeps a global install and both skills current; for a folder install, run `npm update @orchestraworks/cli` in that folder.
-
 ## License
 
-Apache License 2.0. The full text is in [LICENSE](LICENSE).
+Apache License 2.0. The full text is in [LICENSE](https://unpkg.com/@orchestraworks/cli/LICENSE).

package/dist/cli/core/banner.d.ts

@@ -0,0 +1,10 @@
+export interface BannerTerminal {
+    readonly isTTY?: boolean;
+    readonly columns?: number;
+}
+/**
+ * The banner and a blank line, or the empty string. `NO_COLOR` follows no-color.org: any non-empty value
+ * turns it off. `COLORTERM` of `truecolor` or `24bit` selects 24-bit color. A terminal narrower than the
+ * mark and the wordmark gets the mark with the plain word beside its centre.
+ */
+export declare function helpBanner(terminal: BannerTerminal, env: NodeJS.ProcessEnv): string;

package/dist/cli/core/banner.js

@@ -0,0 +1,63 @@
+// The Orchestra mark at the top of bare `orchestra` and `orchestra --help`, for a person at a terminal.
+// A coding agent usually reads piped output, so the banner prints only to a terminal with color allowed:
+// piped output stays plain text with no escape codes.
+/**
+ * The console's 48-dot mark (`console/src/components/BrandMark.tsx`), its circles rasterized onto a
+ * 42-by-40 dot grid and written as braille, eight dots to a character.
+ */
+const MARK = [
+    "⠀⠀⠀⠀⢀⣤⡀⠀⠀⣴⣶⡄⣼⣿⡆⠀⠀⠀⠀⠀⠀",
+    "⠀⠀⠀⠀⠹⠿⠧⣿⡆⠈⠉⣶⡌⢹⣷⡄⢀⣀⠀⠀⠀",
+    "⢠⣶⣄⣿⡷⢰⣶⠀⠀⠿⠀⢈⡀⢀⣭⠀⢿⡿⠂⠀⠀",
+    "⠘⠛⢋⣤⡀⢠⡄⠀⠶⠀⠀⠈⠁⠈⠉⠀⣿⠆⣾⣿⡇",
+    "⢰⣿⡯⠙⣁⠀⠀⣤⠀⠀⠉⠀⠙⠀⠰⠆⠀⢴⣿⡍⠀",
+    "⠀⠉⣤⣌⠛⠀⣤⠀⠀⠒⠀⣀⠀⢴⠄⠐⠿⠂⣩⣄⠀",
+    "⠀⣤⣿⠋⣤⡄⢀⡀⠀⠦⠀⢀⠀⢀⣤⠀⣶⣮⠿⠿⠀",
+    "⠀⠻⠟⢁⣭⡅⠈⡋⠀⣀⡀⠛⢀⣤⡁⣠⣍⠁⠀⠀⠀",
+    "⠀⠀⠀⠘⣻⣧⡸⠿⣂⡙⢣⣤⡄⣙⡁⠻⠟⠀⠀⠀⠀",
+    "⠀⠀⠀⠀⠻⠿⠇⠸⣿⠗⠈⠛⠹⣿⡿⠀⠀⠀⠀⠀⠀",
+];
+/** "ORCHESTRA" in the figlet ANSI Shadow face. */
+const WORDMARK = [
+    " ██████╗ ██████╗  ██████╗██╗  ██╗███████╗███████╗████████╗██████╗  █████╗ ",
+    "██╔═══██╗██╔══██╗██╔════╝██║  ██║██╔════╝██╔════╝╚══██╔══╝██╔══██╗██╔══██╗",
+    "██║   ██║██████╔╝██║     ███████║█████╗  ███████╗   ██║   ██████╔╝███████║",
+    "██║   ██║██╔══██╗██║     ██╔══██║██╔══╝  ╚════██║   ██║   ██╔══██╗██╔══██║",
+    "╚██████╔╝██║  ██║╚██████╗██║  ██║███████╗███████║   ██║   ██║  ██║██║  ██║",
+    " ╚═════╝ ╚═╝  ╚═╝ ╚═════╝╚═╝  ╚═╝╚══════╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚═╝  ╚═╝",
+];
+const MARK_WIDTH = MARK[0].length;
+const GAP = "   ";
+/** The mark and the wordmark side by side. */
+const BANNER_WIDTH = MARK_WIDTH + GAP.length + WORDMARK[0].length;
+/** The first mark row the wordmark sits on, which centres it on the mark. */
+const WORDMARK_TOP = Math.floor((MARK.length - WORDMARK.length) / 2);
+const WORD = "Orchestra";
+/** The console's light-theme accent, `consolePalette.json` `light.accent`, as 24-bit RGB. */
+const ACCENT_TRUE_COLOR = "\u001b[38;2;66;99;235m";
+/** The nearest color in the 256-color table, for a terminal that does not announce 24-bit color. */
+const ACCENT_256 = "\u001b[38;5;63m";
+const BOLD = "\u001b[1m";
+const RESET = "\u001b[0m";
+/**
+ * The banner and a blank line, or the empty string. `NO_COLOR` follows no-color.org: any non-empty value
+ * turns it off. `COLORTERM` of `truecolor` or `24bit` selects 24-bit color. A terminal narrower than the
+ * mark and the wordmark gets the mark with the plain word beside its centre.
+ */
+export function helpBanner(terminal, env) {
+    if (terminal.isTTY !== true || (env.NO_COLOR ?? "") !== "") {
+        return "";
+    }
+    const accent = /^(truecolor|24bit)$/i.test(env.COLORTERM ?? "") ? ACCENT_TRUE_COLOR : ACCENT_256;
+    const wide = (terminal.columns ?? BANNER_WIDTH) >= BANNER_WIDTH;
+    const lines = MARK.map((row, index) => {
+        if (wide) {
+            const word = WORDMARK[index - WORDMARK_TOP];
+            return word === undefined ? `${accent}${row}${RESET}` : `${accent}${row}${GAP}${word.trimEnd()}${RESET}`;
+        }
+        return index === Math.floor(MARK.length / 2)
+            ? `${accent}${row}${RESET}${GAP}${BOLD}${WORD}${RESET}`
+            : `${accent}${row}${RESET}`;
+    });
+    return `${lines.join("\n")}\n\n`;
+}

package/dist/cli/core/package-root.d.ts

@@ -1,11 +1,12 @@
+import { type KitSkill } from "../skill-install-fs.js";
 /**
  * The package root this process runs from. Under `npx orchestra` outside an installed folder this is npm's
  * disposable cache, which `skills install` refuses to link into.
  */
 export declare function runningPackageRoot(): string;
 /**
- * The bundled authoring skill's path, or `null` when this install does not carry it. The exists-guard is the
+ * A bundled skill's path, or `null` when this install does not carry it. The exists-guard is the
  * contract: callers print this as a pointer to follow, and pointing a reader at a path with nothing behind
  * it is a worse repair than printing none. `packageRoot` is the test seam.
  */
-export declare function resolveBundledSkillPath(packageRoot?: string): string | null;
+export declare function resolveBundledSkillPath(packageRoot?: string, skill?: KitSkill): string | null;

package/dist/cli/core/package-root.js

@@ -6,7 +6,7 @@
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { SKILL_DIR_IN_PACKAGE, SKILL_FILE_NAME } from "../skill-install-fs.js";
+import { SKILL_FILE_NAME, skillPackageDir } from "../skill-install-fs.js";
 /**
  * The package root this process runs from. Under `npx orchestra` outside an installed folder this is npm's
  * disposable cache, which `skills install` refuses to link into.
@@ -15,11 +15,11 @@ export function runningPackageRoot() {
     return fileURLToPath(new URL("../../..", import.meta.url));
 }
 /**
- * The bundled authoring skill's path, or `null` when this install does not carry it. The exists-guard is the
+ * A bundled skill's path, or `null` when this install does not carry it. The exists-guard is the
  * contract: callers print this as a pointer to follow, and pointing a reader at a path with nothing behind
  * it is a worse repair than printing none. `packageRoot` is the test seam.
  */
-export function resolveBundledSkillPath(packageRoot = runningPackageRoot()) {
-    const skillPath = join(packageRoot, SKILL_DIR_IN_PACKAGE, SKILL_FILE_NAME);
+export function resolveBundledSkillPath(packageRoot = runningPackageRoot(), skill = "orchestra") {
+    const skillPath = join(packageRoot, skillPackageDir(skill), SKILL_FILE_NAME);
     return existsSync(skillPath) ? skillPath : null;
 }

package/dist/cli/core/skill-pointer.d.ts

@@ -5,10 +5,15 @@ export interface SkillPointer {
     readonly fields: {
         readonly skillPath: string;
     };
+    /**
+     * The lines `orchestra` and `orchestra --help` end with. A coding agent often runs the help right after the
+     * install, and npm hides install-script output, so this tail is where the agent learns which skill to read.
+     */
+    readonly helpEpilogue: readonly string[];
 }
 /**
  * `null` when this install carries no bundled manual, in which case every surface prints nothing at all.
- * Omission is the contract, not a degraded mode. `skillPath` is the test seam.
+ * Omission is the contract, not a degraded mode. `skillPath` and `setupSkillPath` are the test seams.
  */
-export declare function bundledSkillPointer(skillPath?: string | null): SkillPointer | null;
+export declare function bundledSkillPointer(skillPath?: string | null, setupSkillPath?: string | null): SkillPointer | null;
 export declare function emitSkillPointer(io: CliIo, pointer?: SkillPointer | null): void;

package/dist/cli/core/skill-pointer.js

@@ -1,13 +1,23 @@
 import { resolveBundledSkillPath } from "./package-root.js";
 /**
  * `null` when this install carries no bundled manual, in which case every surface prints nothing at all.
- * Omission is the contract, not a degraded mode. `skillPath` is the test seam.
+ * Omission is the contract, not a degraded mode. `skillPath` and `setupSkillPath` are the test seams.
  */
-export function bundledSkillPointer(skillPath = resolveBundledSkillPath()) {
+export function bundledSkillPointer(skillPath = resolveBundledSkillPath(), setupSkillPath = resolveBundledSkillPath(undefined, "orchestra-fdk")) {
     if (skillPath === null) {
         return null;
     }
-    return { line: `Learn orchestra: read ${skillPath}`, fields: { skillPath } };
+    return {
+        line: `Learn orchestra: read ${skillPath}`,
+        fields: { skillPath },
+        helpEpilogue: [
+            "Coding agents: read both skills before you start.",
+            `  To learn how to use the orchestra CLI, read ${skillPath}`,
+            ...(setupSkillPath === null ? [] : [`  To set up a factory, read ${setupSkillPath}`]),
+            "  To link both skills into your harness, run:",
+            "  orchestra skills install --harness claude|codex --scope project",
+        ],
+    };
 }
 export function emitSkillPointer(io, pointer = bundledSkillPointer()) {
     if (pointer !== null) {

package/dist/cli/main.js

@@ -37,6 +37,7 @@ import { DEFAULT_TEMPLATE, initCommand, MODEL_KEY_CHOICES, OFFERED_TEMPLATES } f
 import { grantCommand } from "./api/grant.js";
 import { addAuthOptions } from "./core/invocation.js";
 import { errorDocument, reportError, settleExitCode } from "./core/errors.js";
+import { helpBanner } from "./core/banner.js";
 import { bundledSkillPointer, emitSkillPointer } from "./core/skill-pointer.js";
 import { outputModeFromArgv } from "./core/output-mode.js";
 import { defaultIo, writeLines } from "./core/output.js";
@@ -170,7 +171,7 @@ LEARN MORE
  * entirely. `pointer` is the test seam.
  */
 export function topLevelHelpText(pointer = bundledSkillPointer()) {
-    return pointer === null ? TOP_LEVEL_HELP : `${TOP_LEVEL_HELP}\n${pointer.line}\n`;
+    return pointer === null ? TOP_LEVEL_HELP : `${TOP_LEVEL_HELP}\n${pointer.helpEpilogue.join("\n")}\n`;
 }
 const REQUIRE_APPROVAL_HELP = requireApprovalHelp(IMPERATIVE_APPROVAL_DEFAULT);
 /**
@@ -294,9 +295,10 @@ export function buildProgram(handlers = defaultHandlers, pointer = bundledSkillP
     // Deliberately an own-property assignment and NOT `configureHelp`: commander copies `_helpConfiguration`
     // into every subcommand created afterwards, so configuring the formatter here would make every
     // `--help` print the top-level text too. The text is computed once and the closure returns that same
-    // string every time, so `--help` printed twice in one process cannot disagree with itself.
+    // string every time, so `--help` printed twice in one process cannot disagree with itself. The banner
+    // above it depends on the stream the help goes to: stderr for a bare `orchestra`, stdout for `--help`.
     const helpText = topLevelHelpText(pointer);
-    program.helpInformation = () => helpText;
+    program.helpInformation = (context) => `${helpBanner(context?.error === true ? process.stderr : process.stdout, process.env)}${helpText}`;
     // Registered on the program, which is where commander looks: it walks a command's ancestors when an action
     // fires, so one hook here covers the whole tree. It runs after parsing, so `--help` and a usage error —
     // both of which end during the parse — never reach it.

package/dist/cli/skill-install-fs.d.ts

@@ -10,8 +10,6 @@ export declare const KIT_INSTALL_SPEC = "@orchestraworks/cli";
 export declare const KIT_SKILLS: readonly ["orchestra", "orchestra-fdk"];
 export type KitSkill = (typeof KIT_SKILLS)[number];
 export declare function skillPackageDir(skill: KitSkill): string;
-/** The reference skill's directory, which the CLI's own pointer names. */
-export declare const SKILL_DIR_IN_PACKAGE: string;
 export declare const SKILL_FILE_NAME = "SKILL.md";
 /** "other" is a printed-path branch, never a link target. */
 export type LinkableHarness = "claude" | "codex";

package/dist/cli/skill-install-fs.js

@@ -16,8 +16,6 @@ export const KIT_SKILLS = ["orchestra", "orchestra-fdk"];
 export function skillPackageDir(skill) {
     return join("skills", skill);
 }
-/** The reference skill's directory, which the CLI's own pointer names. */
-export const SKILL_DIR_IN_PACKAGE = skillPackageDir("orchestra");
 export const SKILL_FILE_NAME = "SKILL.md";
 /**
  * Identical under a project root and under `$HOME`. The ONE home for these strings: the link math, the menu

package/node_modules/@orchestraworks/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/client",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "Orchestra public API TypeScript client",
   "author": "Living Computers",
   "repository": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestraworks/cli",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "description": "The Orchestra command line.",
   "license": "Apache-2.0",
@@ -109,7 +109,7 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.3.0",
-    "@orchestraworks/client": "0.5.0",
+    "@orchestraworks/client": "0.5.1",
     "@orchestraworks/worker": "0.0.136",
     "commander": "^14.0.0",
     "liquidjs": "^10.28.0"