@north-light/crouter 0.3.154

package/dist/core/fs-utils.js

@@ -0,0 +1,149 @@
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, writeFileSync, cpSync, readlinkSync, renameSync, chmodSync, } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { platform } from 'node:os';
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+export function writeJson(path, data) {
+    ensureDir(dirname(path));
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf8');
+}
+export function atomicWriteJson(path, data) {
+    ensureDir(dirname(path));
+    const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+    try {
+        writeFileSync(temp, JSON.stringify(data, null, 2) + '\n', { encoding: 'utf8', mode });
+        chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+}
+export function atomicWriteText(path, content) {
+    ensureDir(dirname(path));
+    const temp = `${path}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`;
+    const mode = existsSync(path) ? statSync(path).mode & 0o777 : 0o600;
+    try {
+        writeFileSync(temp, content, { mode });
+        chmodSync(temp, mode);
+        renameSync(temp, path);
+    }
+    finally {
+        if (existsSync(temp))
+            rmSync(temp, { force: true });
+    }
+}
+export function readJson(path) {
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+export function readJsonIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    return readJson(path);
+}
+export function readTextIfExists(path) {
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, 'utf8');
+}
+export function readText(path) {
+    return readFileSync(path, 'utf8');
+}
+export function writeText(path, content) {
+    ensureDir(dirname(path));
+    writeFileSync(path, content, 'utf8');
+}
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function isSymlink(path) {
+    try {
+        return lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function pathExists(path) {
+    return existsSync(path);
+}
+export function listDirs(path) {
+    if (!existsSync(path))
+        return [];
+    return readdirSync(path, { withFileTypes: true })
+        .filter((d) => d.isDirectory() || d.isSymbolicLink())
+        .map((d) => d.name);
+}
+export function listEntries(path) {
+    if (!existsSync(path))
+        return [];
+    return readdirSync(path);
+}
+export function removePath(path) {
+    if (!existsSync(path) && !isSymlink(path))
+        return;
+    rmSync(path, { recursive: true, force: true });
+}
+export function linkOrCopy(target, linkPath, opts = {}) {
+    ensureDir(dirname(linkPath));
+    removePath(linkPath);
+    const isWindows = platform() === 'win32';
+    if (!opts.noSymlink && !isWindows) {
+        const rel = relative(dirname(linkPath), target);
+        try {
+            symlinkSync(rel, linkPath, isDir(target) ? 'dir' : 'file');
+            return 'symlink';
+        }
+        catch {
+            cpSync(target, linkPath, { recursive: true });
+            return 'copy';
+        }
+    }
+    cpSync(target, linkPath, { recursive: true });
+    return 'copy';
+}
+export function readSymlinkTarget(path) {
+    try {
+        return readlinkSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+export function walkFiles(root, predicate = () => true, skipDir = () => false) {
+    const out = [];
+    if (!existsSync(root))
+        return out;
+    const stack = [root];
+    while (stack.length) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const e of entries) {
+            const full = join(dir, e.name);
+            if (e.isDirectory()) {
+                if (!skipDir(e.name))
+                    stack.push(full);
+            }
+            else if (e.isFile() && predicate(e.name))
+                out.push(full);
+        }
+    }
+    return out;
+}
+export function nowIso() {
+    return new Date().toISOString();
+}

package/dist/core/git.d.ts

@@ -0,0 +1,22 @@
+export interface GitResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+export interface GitSyncOptions {
+    timeoutMs?: number;
+}
+export declare function gitSync(args: string[], cwd?: string, input?: string, options?: GitSyncOptions): GitResult;
+export declare function gitAsync(args: string[], cwd?: string): Promise<GitResult>;
+export declare function clone(url: string, dest: string, opts?: {
+    ref?: string;
+    depth?: number;
+}): GitResult;
+export declare function pull(cwd: string): GitResult;
+export declare function fetch(cwd: string, ref?: string): GitResult;
+export declare function lsRemote(url: string): GitResult;
+export declare function currentSha(cwd: string): string | null;
+export declare function remoteSha(cwd: string, ref: string): string | null;
+export declare function isGitRepo(cwd: string): boolean;
+export declare function deriveNameFromUrl(url: string): string;

package/dist/core/git.js

@@ -0,0 +1,72 @@
+import { spawn, spawnSync } from 'node:child_process';
+import { network } from './errors.js';
+export function gitSync(args, cwd, input, options = {}) {
+    const res = spawnSync('git', args, { cwd, encoding: 'utf8', input, timeout: options.timeoutMs });
+    const status = typeof res.status === 'number' ? res.status : 1;
+    const stdout = typeof res.stdout === 'string' ? res.stdout : '';
+    const stderr = typeof res.stderr === 'string' ? res.stderr : '';
+    const timedOut = res.error?.code === 'ETIMEDOUT';
+    return { status, stdout, stderr, ...(timedOut ? { timedOut: true } : {}) };
+}
+export async function gitAsync(args, cwd) {
+    return new Promise((resolve) => {
+        const child = spawn('git', args, { cwd });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.on('data', (d) => (stdout += d.toString()));
+        child.stderr.on('data', (d) => (stderr += d.toString()));
+        child.on('close', (status) => {
+            const code = typeof status === 'number' ? status : 1;
+            resolve({ status: code, stdout, stderr });
+        });
+        child.on('error', (e) => resolve({ status: 1, stdout: '', stderr: String(e) }));
+    });
+}
+export function clone(url, dest, opts = {}) {
+    const args = ['clone'];
+    if (opts.depth)
+        args.push('--depth', String(opts.depth));
+    if (opts.ref)
+        args.push('--branch', opts.ref);
+    args.push(url, dest);
+    const res = gitSync(args);
+    if (res.status !== 0) {
+        throw network(`git clone failed: ${url}\n${res.stderr.trim()}`);
+    }
+    return res;
+}
+export function pull(cwd) {
+    return gitSync(['pull', '--ff-only'], cwd);
+}
+export function fetch(cwd, ref) {
+    const args = ['fetch', 'origin'];
+    if (ref)
+        args.push(ref);
+    return gitSync(args, cwd);
+}
+export function lsRemote(url) {
+    return gitSync(['ls-remote', url]);
+}
+export function currentSha(cwd) {
+    const res = gitSync(['rev-parse', 'HEAD'], cwd);
+    if (res.status !== 0)
+        return null;
+    return res.stdout.trim();
+}
+export function remoteSha(cwd, ref) {
+    const res = gitSync(['rev-parse', `origin/${ref}`], cwd);
+    if (res.status !== 0)
+        return null;
+    return res.stdout.trim();
+}
+export function isGitRepo(cwd) {
+    const res = gitSync(['rev-parse', '--is-inside-work-tree'], cwd);
+    return res.status === 0 && res.stdout.trim() === 'true';
+}
+export function deriveNameFromUrl(url) {
+    const trimmed = url.replace(/\.git\/?$/, '').replace(/\/$/, '');
+    const last = trimmed.split('/').pop();
+    if (!last)
+        return url;
+    return last;
+}

package/dist/core/help.d.ts

@@ -0,0 +1,223 @@
+export interface Field {
+    name: string;
+    type: string;
+    required: boolean;
+    /** Inline semantic constraint — bounds, enum, "must reference an active plan",
+     *  token caps. Lives here, never in a separate Preconditions section. */
+    constraint: string;
+}
+/** Positional argument — at most one per leaf. */
+export interface PositionalParam {
+    kind: 'positional';
+    name: string;
+    /** Display hint only; always parsed as string. */
+    type?: 'string' | 'path';
+    required: boolean;
+    constraint: string;
+    /** Local-file materialization contract, valid only on a `path` param. The
+     *  CLI-side value is a path to a local file; the invoker reads that file and
+     *  sends its CONTENT as the mapped value — 'text' as UTF-8, 'base64' as the
+     *  base64 of its raw bytes. The path string itself never crosses the wire. */
+    encoding?: FileEncoding;
+    /** Ambient default: when the caller omits this param and the named client
+     *  environment variable is set and non-empty, that value is used and counts as
+     *  supplied — see FlagParam.defaultFromEnv. */
+    defaultFromEnv?: string;
+}
+/** How a local file named by a `path` param is encoded into the request. */
+export type FileEncoding = 'text' | 'base64';
+/** Long-form flag (`--name`). */
+export interface FlagParam {
+    kind: 'flag';
+    name: string;
+    /** 'bool' flags take no value — presence = true. */
+    type: 'string' | 'int' | 'bool' | 'path' | 'enum';
+    /** Required only when type is 'enum'. */
+    choices?: string[];
+    required: boolean;
+    constraint: string;
+    default?: string | number | boolean;
+    /** When true, the flag may appear multiple times; values accumulate into an
+     *  array (parseArgv collects them; body-placed REST params ship as a JSON array). */
+    repeatable?: boolean;
+    /** When true, the flag is PARSED normally but never rendered in `-h`. For a
+     *  deliberately-undiscoverable confirmation gate the agent must be TOLD about
+     *  in the command's own output (not by reading the schema), never advertised. */
+    hidden?: boolean;
+    /** Local-file materialization contract, valid only on a `path` flag — see
+     *  PositionalParam.encoding. */
+    encoding?: FileEncoding;
+    /** Ambient default sourced from the CALLER's environment: when the param is
+     *  not supplied on the command line and this environment variable is set and
+     *  non-empty, its value fills the param and counts as explicitly supplied (it
+     *  therefore satisfies `required` and ships like a typed value — unlike a
+     *  static `default`, which is a display/parse convenience only). This is how a
+     *  leaf picks up ambient identity a caller should not have to retype, e.g.
+     *  CRTR_NODE_ID, which every broker exports into its node's environment. */
+    defaultFromEnv?: string;
+}
+/** Raw stdin content blob (piped text, not parsed as JSON). */
+export interface StdinParam {
+    kind: 'stdin';
+    name: string;
+    required: boolean;
+    constraint: string;
+}
+/** --context-file PATH: reads and JSON-parses the file at PATH. */
+export interface ContextFileParam {
+    kind: 'context-file';
+    name: string;
+    required: boolean;
+    constraint: string;
+    /** Optional description of the expected JSON shape. */
+    shape?: string;
+}
+export type InputParam = PositionalParam | FlagParam | StdinParam | ContextFileParam;
+/** How prominently a subcommand surfaces in ancestor (parent / root) -h
+ *  listings. Set per child in the parent branch's `help.children`. Default
+ *  'normal'.
+ *   - hidden    — never listed anywhere, not even in this branch's own -h.
+ *                 You must already know it exists to invoke it.
+ *   - normal    — listed in this branch's own -h only (the default).
+ *   - common    — ALSO promoted into the parent's -h, as a bare qualified name.
+ *   - important — ALSO promoted into the parent's -h, name + shortform desc. */
+export type SubTier = 'hidden' | 'normal' | 'common' | 'important';
+/** A child's assembled parent-level listing entry — computed by defineBranch
+ *  from each child def's own self-description (`description`/`whenToUse`/`tier`).
+ *  renderBranch consumes this; it is never authored by hand and there is no
+ *  parent-side copy of a child's description (principle 16: each node owns its
+ *  representation one level up). */
+export interface ListingChild {
+    name: string;
+    /** Short description for this child's <subcommand> row. */
+    description: string;
+    /** Selection rubric — plainly states when to reach for this command. Expansive
+     *  with a variety of examples for judgment-heavy commands; concise for
+     *  genuinely single-purpose ones. Rendered verbatim (no prefix). */
+    whenToUse: string;
+    /** Visibility tier in ancestor listings (see SubTier). 'hidden' children are
+     *  dropped from every listing. */
+    tier: SubTier;
+    /** How many non-hidden subcommands this child itself owns — drives the
+     *  `subcommands="N"` attribute when a branch child is listed without
+     *  expansion. Absent for leaves and childless branches. */
+    subCount?: number;
+}
+/** A subtree's self-description at the parent (root) level. Each subtree owns
+ *  the content that represents it one level up: its vocabulary line, its
+ *  selection rubric, and any bounded block it contributes to the parent's -h.
+ *  defineRoot assembles the root help from these — root never hardcodes a
+ *  subtree's representation. See cli-design "Each node owns its parent-level
+ *  representation". */
+export interface RootEntry {
+    /** One-line vocabulary desc — what this subtree is. Rendered first in the
+     *  subtree's <name> block at root. */
+    concept: string;
+    /** Operations summary (verb list). Carried for completeness; the root block
+     *  leads with concept + rubric, so this is available but not rendered. */
+    desc: string;
+    /** The selection rubric — `use when X` in the subtree's <name> block. */
+    useWhen: string;
+    /** Optional bounded block this subtree contributes to its <name> block at
+     *  root. Returns a complete self-named state element (build it with
+     *  stateBlock), e.g. `<kinds count="7">…</kinds>`. Aggregate, never an
+     *  unbounded enumeration on a cold path. Soft-fails to omission on
+     *  null/throw. */
+    dynamicState?: () => string | null;
+}
+export interface RootHelp {
+    tagline: string;
+    /** One entry per listed subtree. Each renders as its own <name> XML block at
+     *  root, carrying the subtree's concept, selection rubric, and any nested
+     *  runtime-state block. Assembled from subtrees' RootEntry by defineRoot;
+     *  root hardcodes none of it. */
+    commands: RootCommand[];
+    globals: {
+        name: string;
+        desc: string;
+    }[];
+}
+/** A single command block at root. Most fields come from the subtree's
+ *  RootEntry; `subcommands`/`otherSubcommandCount` are computed by defineRoot
+ *  from the subtree's children tiers. */
+export interface RootCommand {
+    name: string;
+    concept: string;
+    desc: string;
+    useWhen: string;
+    dynamicState?: () => string | null;
+    /** Promoted subcommands surfaced inline under this command at root, in
+     *  declaration order. `desc` is present only for 'important' tier; 'common'
+     *  tier carries the bare qualified path. */
+    subcommands?: {
+        path: string;
+        desc?: string;
+    }[];
+    /** How many of this command's other (non-hidden, not-promoted) direct
+     *  subcommands are not shown. Drives the "[+N (other) subcommands]" line. */
+    otherSubcommandCount?: number;
+}
+export interface BranchHelp {
+    name: string;
+    /** The command's own description — rendered as the `description` attribute of
+     *  its <command> card at its own -h. */
+    summary: string;
+    /** Local model prose orienting the agent to what the subtree contains and how
+     *  the children differ as a group — never a per-child restatement (each
+     *  child's purpose lives in its own listing row). */
+    model?: string;
+    /** Bounded runtime aggregate as a complete self-named state element (build
+     *  it with stateBlock), e.g. `<kinds count="7">…</kinds>`. Renderer
+     *  soft-fails to omission if this returns null or throws. */
+    dynamicState?: () => string | null;
+    /** Parent-level listing assembled by defineBranch from the actual child defs.
+     *  renderBranch reads this; never author it by hand. */
+    listing?: ListingChild[];
+}
+/** Viewer-only hint about how a leaf's result should preview in the attach
+ *  viewer's chat — never part of `-h` output and never reaches agent-facing
+ *  stdout (see renderLeafArgv / renderResult, neither of which read this
+ *  field). Declared on the leaf that owns the behavior, so the attach viewer
+ *  asks the command tree instead of guessing from rendered text. */
+export interface PreviewMeta {
+    /** When true, the attach viewer collapses this leaf's successful result to
+     *  a one-line status by default (still expandable with Ctrl+O). For a
+     *  command whose result is a machine-readable dump meant for a browser/tool
+     *  rather than a human glance (e.g. a snapshot leaf). Never suppresses a
+     *  failed run — errors always show in full. */
+    suppressOutput?: boolean;
+}
+export interface LeafHelp {
+    name: string;
+    summary: string;
+    /** Optional long-form workflow prose rendered immediately after the summary
+     *  line. Only plan new / spec new carry this; it precedes the schema. */
+    guide?: string;
+    params?: InputParam[];
+    /** Note appended when there is no input (replaces the Input block). */
+    inputNote?: string;
+    output: Field[];
+    outputKind: 'object' | 'jsonl';
+    /** Every persistent change the command makes to the world. For read-only
+     *  leaves use exactly: ["None. Read-only."] */
+    effects: string[];
+    /** Bounded runtime aggregate as a complete self-named state element (build it
+     *  with stateBlock), e.g. `<kinds count="7">…</kinds>`. Lazily evaluated at
+     *  render time so it reflects the caller's cwd/project scope; appended after
+     *  the schema. Renderer soft-fails to omission if it returns null or throws.
+     *  Mirrors BranchHelp.dynamicState. */
+    dynamicState?: () => string | null;
+    /** Attach-viewer preview hint (see PreviewMeta). Optional; omit for the
+     *  default preview behaviour. */
+    preview?: PreviewMeta;
+}
+/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
+ *  subtree that owns the state authors it through this, so the tag name and any
+ *  scalar metadata (e.g. a count) travel with the data and render identically
+ *  at every level the block appears. The tag name carries the label, so the
+ *  body never repeats it. Attribute values are controlled (counts, short
+ *  tokens) and not escaped. */
+export declare function stateBlock(tag: string, attrs: Record<string, string | number>, body: string): string;
+export declare function renderRoot(h: RootHelp): string;
+export declare function renderBranch(h: BranchHelp): string;
+export declare function renderLeafArgv(h: LeafHelp): string;