@north-light/api 0.3.580 → 0.3.587

package/dist/commands/sys/sync-skills.js

@@ -0,0 +1,297 @@
+// `crtr sys sync skills` — one-way import of legacy host Agent Skill bundles
+// (SKILL.md) as documents owned by the person (user skill roots) or by the
+// repo of the working directory (project skill roots). Not a bidirectional
+// SKILL.md sync surface: after a sync the crouter side is a plain document.
+import { existsSync } from 'node:fs';
+import { userFilesRoot } from '../../core/layout.js';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { defineLeaf } from '../../core/command.js';
+import { usage } from '../../core/errors.js';
+import { parseFrontmatterGeneric } from '../../core/frontmatter.js';
+import { readJsonIfExists, readText, walkFiles, writeJson } from '../../core/fs-utils.js';
+import { readLegacyPrivacy } from '../../core/graph/types.js';
+import { identifyCheckout } from '../../core/graph/repo-sync/identity.js';
+import { runtimeRoot } from '../../core/layout.js';
+import { piAgentDir } from '../../core/runtime/package-health.js';
+import { CRTR_DIR_NAME } from '../../types.js';
+import { cliClient } from '../api-client.js';
+import { normalizedName, putDoc, repoOwner, routeFromDescription, rulesFromLegacyFrontmatter, scalarString, userOwner, writeFailure, } from './sync-shared.js';
+const LEGACY_BOOT_SKILL_MARKER_PREFIX = '<!-- crtr-boot-skill v';
+const HOST_SKILL_FILE = 'SKILL.md';
+const IGNORE_FILE = 'skill-import-ignore.json';
+// Directories a skill-root walk never descends into — build/dependency trees
+// plus crouter's own state dir.
+const SKILL_WALK_JUNK_DIRS = new Set([
+    'node_modules', '.git', '.venv', 'venv', 'dist', 'build', '.next', '.cache', '.yalc', '.sisyphus', CRTR_DIR_NAME,
+]);
+function projectDir() {
+    const id = identifyCheckout(process.cwd());
+    return id.ok ? id.root : null;
+}
+function ignoreFilePath() {
+    return join(runtimeRoot(), IGNORE_FILE);
+}
+function defaultSourceRoots() {
+    const roots = [
+        { label: 'claude-user', root: join(userFilesRoot(), '.claude', 'skills'), defaultScope: 'user' },
+        { label: 'pi-user', root: join(piAgentDir(), 'skills'), defaultScope: 'user' },
+    ];
+    const proj = projectDir();
+    if (proj) {
+        roots.push({ label: 'claude-project', root: join(proj, '.claude', 'skills'), defaultScope: 'project' });
+        roots.push({ label: 'pi-project', root: join(proj, '.pi', 'agent', 'skills'), defaultScope: 'project' });
+    }
+    return roots;
+}
+function sourceRootsFromArg(sourceArg, scopeArg) {
+    if (sourceArg === undefined)
+        return defaultSourceRoots();
+    const root = resolve(sourceArg);
+    if (scopeArg !== undefined && scopeArg !== 'user' && scopeArg !== 'project') {
+        throw usage(`invalid --scope: ${scopeArg} (expected user|project)`);
+    }
+    return [{ label: 'source', root, defaultScope: scopeArg ?? 'user' }];
+}
+function collectCandidates(rootDef) {
+    const root = rootDef.root;
+    if (!existsSync(root))
+        return [];
+    const statRoot = resolve(root);
+    const candidates = [];
+    if (basename(statRoot) === HOST_SKILL_FILE) {
+        candidates.push({ path: statRoot, root: dirname(statRoot), source: rootDef.label, defaultScope: rootDef.defaultScope });
+        return candidates;
+    }
+    const directSkill = join(statRoot, HOST_SKILL_FILE);
+    if (existsSync(directSkill)) {
+        candidates.push({ path: directSkill, root: dirname(statRoot), source: rootDef.label, defaultScope: rootDef.defaultScope });
+        return candidates;
+    }
+    for (const file of walkFiles(statRoot, (name) => name === HOST_SKILL_FILE, (name) => SKILL_WALK_JUNK_DIRS.has(name))) {
+        candidates.push({ path: file, root: statRoot, source: rootDef.label, defaultScope: rootDef.defaultScope });
+    }
+    return candidates;
+}
+function nameForCandidate(candidate, fm) {
+    const fmName = scalarString(fm?.name);
+    if (fmName && fmName.trim() !== '')
+        return normalizedName(fmName);
+    const relDir = relative(candidate.root, dirname(candidate.path)).split(sep).join('/');
+    return normalizedName(relDir || basename(dirname(candidate.path)));
+}
+function ownerResolver(client) {
+    const cache = new Map();
+    return (scope) => {
+        let owner = cache.get(scope);
+        if (owner === undefined) {
+            owner = scope === 'user' ? userOwner(client) : repoOwner(client, process.cwd());
+            cache.set(scope, owner);
+        }
+        return owner;
+    };
+}
+function readIgnoreState() {
+    let doc;
+    try {
+        doc = readJsonIfExists(ignoreFilePath());
+    }
+    catch (e) {
+        throw usage(`invalid JSON in ${ignoreFilePath()}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    if (doc === null)
+        return { version: 1, ignored: [] };
+    if (typeof doc !== 'object' ||
+        doc === null ||
+        doc.version !== 1 ||
+        !Array.isArray(doc.ignored)) {
+        throw usage(`malformed ${ignoreFilePath()}: expected {"version":1,"ignored":[...]}`);
+    }
+    const ignored = [];
+    for (const entry of doc.ignored) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const e = entry;
+        if (typeof e.source === 'string' &&
+            typeof e.name === 'string' &&
+            (e.scope === 'user' || e.scope === 'project') &&
+            typeof e.ignoredAt === 'string') {
+            ignored.push({ source: resolve(e.source), name: e.name, scope: e.scope, ignoredAt: e.ignoredAt });
+        }
+    }
+    return { version: 1, ignored };
+}
+function writeIgnoreState(state) {
+    writeJson(ignoreFilePath(), state);
+}
+function isIgnored(prepared, state) {
+    const source = resolve(prepared.candidate.path);
+    return state.ignored.some((entry) => entry.source === source ||
+        (entry.scope === prepared.scope && entry.name === prepared.name));
+}
+function rememberIgnored(prepared, state) {
+    if (isIgnored(prepared, state))
+        return false;
+    state.ignored.push({
+        source: resolve(prepared.candidate.path),
+        name: prepared.name,
+        scope: prepared.scope,
+        ignoredAt: new Date().toISOString(),
+    });
+    state.ignored.sort((a, b) => `${a.scope}/${a.name}`.localeCompare(`${b.scope}/${b.name}`));
+    return true;
+}
+function skipResult(candidate, scope, reason) {
+    return { source: candidate.path, name: '', scope, status: 'skipped', reason };
+}
+async function prepareCandidate(candidate, owners, scopeOverride) {
+    const raw = readText(candidate.path);
+    const scope = scopeOverride ?? candidate.defaultScope;
+    if (raw.includes(LEGACY_BOOT_SKILL_MARKER_PREFIX)) {
+        return skipResult(candidate, scope, 'legacy generated crtr boot skill is pruned by host exports, not imported');
+    }
+    const parsed = parseFrontmatterGeneric(raw);
+    const sourceFm = parsed.data ?? {};
+    const kind = sourceFm.kind === 'preference' ? 'preference' : 'knowledge';
+    const localName = nameForCandidate(candidate, sourceFm);
+    if (localName === '')
+        return skipResult(candidate, scope, 'could not derive a document name');
+    const owner = await owners(scope);
+    return { candidate, raw, parsed, sourceFm, kind, localName, name: `${owner.handle}/${localName}`, scope, owner };
+}
+const PRIVACIES = ['public', 'private'];
+async function convertPrepared(client, prepared, opts) {
+    const row = { source: prepared.candidate.path, name: prepared.name, scope: prepared.scope };
+    if (prepared.owner.existing.has(prepared.localName) && !opts.overwrite) {
+        return { ...row, status: 'skipped', reason: 'a document with this name already exists; re-run with --overwrite to replace it' };
+    }
+    if (opts.dryRun)
+        return { ...row, status: 'would-import' };
+    const fm = prepared.sourceFm;
+    const description = scalarString(fm['description']) ?? '';
+    const route = scalarString(fm['when-and-why-to-read'])?.trim();
+    const shortForm = scalarString(fm['short-form'])?.trim();
+    const rules = rulesFromLegacyFrontmatter(fm);
+    const privacy = PRIVACIES.find((p) => p === readLegacyPrivacy(fm['privacy']));
+    const doc = {
+        name: prepared.localName,
+        kind: prepared.kind,
+        preview: (route !== undefined && route !== '' ? route : routeFromDescription(description, prepared.kind)).replace(/\s+/g, ' '),
+        summary: shortForm !== undefined && shortForm !== '' ? shortForm : description.replace(/\s+/g, ' ').trim(),
+        ...(privacy !== undefined ? { privacy } : {}),
+        rules: Array.isArray(fm['surfaces']) ? rules : [{ on: 'boot', deliver: 'preview' }],
+        body: prepared.parsed.body,
+    };
+    try {
+        const r = await putDoc(client, prepared.owner, doc, 'imported by crtr sys sync skills');
+        return { ...row, name: r.name, status: r.changed ? 'imported' : 'unchanged' };
+    }
+    catch (err) {
+        return { ...row, status: 'skipped', reason: writeFailure(err) };
+    }
+}
+function ignoreResult(prepared, reason, dryRun) {
+    return {
+        source: prepared.candidate.path,
+        name: prepared.name,
+        scope: prepared.scope,
+        status: dryRun ? 'would-ignore' : 'ignored',
+        reason,
+    };
+}
+function renderSummary(results, ignoreMode) {
+    const imported = results.filter((r) => r.status === 'imported').length;
+    const wouldImport = results.filter((r) => r.status === 'would-import').length;
+    const skipped = results.filter((r) => r.status === 'skipped').length;
+    const ignored = results.filter((r) => r.status === 'ignored').length;
+    const wouldIgnore = results.filter((r) => r.status === 'would-ignore').length;
+    let header;
+    if (ignoreMode)
+        header = `crtr sys sync skills — ${wouldIgnore > 0 ? `${wouldIgnore} would ignore` : `${ignored} ignored`}, ${skipped} skipped`;
+    else if (wouldImport > 0)
+        header = `crtr sys sync skills — dry run: ${wouldImport} would import, ${skipped} skipped, ${ignored} ignored`;
+    else
+        header = `crtr sys sync skills — ${imported} imported, ${skipped} skipped, ${ignored} ignored`;
+    const rows = results.map((r) => {
+        const reason = r.reason ? ` (${r.reason})` : '';
+        return `| ${r.status} | ${r.name || '—'} | ${r.source}${reason} |`;
+    });
+    const body = rows.length === 0
+        ? ['No sync candidates.']
+        : ['| status | document | source |', '| --- | --- | --- |', ...rows];
+    return [header, '', ...body].join('\n');
+}
+export const sysSyncSkillsLeaf = defineLeaf({
+    name: 'skills',
+    description: 'import host Agent Skill (SKILL.md) bundles as documents',
+    whenToUse: 'migrating legacy host-native Agent Skill bundles (SKILL.md — Claude/pi user or project skill roots, or an explicit bundle/root via --source) into documents. One-way: crouter never re-exports documents back to SKILL.md, and stops reading the originals unconditionally once migrated.',
+    help: {
+        name: 'sys sync skills',
+        summary: 'one-way import: host SKILL.md bundles → documents owned by you or the repo',
+        params: [
+            { kind: 'flag', name: 'source', type: 'string', required: false, constraint: 'A SKILL.md file, a single skill bundle dir containing SKILL.md, or a skills root to scan recursively. Default: the user/project Claude and pi skill roots that exist.' },
+            { kind: 'flag', name: 'scope', type: 'enum', choices: ['user', 'project'], required: false, constraint: 'Owner of the imported documents. `user` — you, the person; `project` — the repo of the working directory (a repo owns only public documents). Default: user for user host roots and project for project host roots; an explicit value applies to every selected source.' },
+            { kind: 'flag', name: 'dry-run', type: 'bool', required: false, constraint: 'Show what would be imported without writing documents.' },
+            { kind: 'flag', name: 'overwrite', type: 'bool', required: false, constraint: 'Replace the body and fields of an existing document of the same name (a new revision). Default: skip it.' },
+            { kind: 'flag', name: 'ignore', type: 'bool', required: false, constraint: `Permanently ignore every selected SKILL.md source by recording it in ~/.crouter/${IGNORE_FILE}. Honors --source/--scope; with no --source, ignores every currently discovered default host skill candidate.` },
+            { kind: 'flag', name: 'include-ignored', type: 'bool', required: false, constraint: 'Include ignored candidates in the report without making sync read-only. Pair with --dry-run to audit the full candidate set without importing non-ignored skills.' },
+        ],
+        output: [
+            { name: 'results', type: 'object[]', required: true, constraint: 'Each: {source,target,name,scope,status,reason?}; status is one of imported, unchanged, skipped, would-import, ignored, would-ignore. `name` is the document\'s full name, `<owner handle>/<bundle name>`.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Writes the document `<owner handle>/<bundle name>` with the SKILL.md body; its preview comes from the skill description, and it carries a boot rule at preview unless the source declares its own `surfaces`.',
+            'Skips existing documents unless --overwrite is present.',
+            'Skips marker-bearing generated crtr boot skills; host exports prune those legacy artifacts instead.',
+            `With --ignore: writes ~/.crouter/${IGNORE_FILE} and does not import the selected sources.`,
+            'With --dry-run: read-only; writes nothing.',
+        ],
+    },
+    run: async (input) => {
+        const sourceArg = input['source'];
+        const scopeArg = input['scope'];
+        const dryRun = input['dryRun'] ?? false;
+        const overwrite = input['overwrite'] ?? false;
+        const ignoreMode = input['ignore'] ?? false;
+        const includeIgnored = input['includeIgnored'] ?? false;
+        const roots = sourceRootsFromArg(sourceArg, scopeArg);
+        const seen = new Set();
+        const candidates = [];
+        for (const root of roots) {
+            for (const c of collectCandidates(root)) {
+                if (seen.has(c.path))
+                    continue;
+                seen.add(c.path);
+                candidates.push(c);
+            }
+        }
+        const client = cliClient();
+        const owners = ownerResolver(client);
+        const ignoreState = readIgnoreState();
+        const results = [];
+        let changedIgnoreState = false;
+        for (const candidate of candidates) {
+            const prepared = await prepareCandidate(candidate, owners, scopeArg);
+            if ('status' in prepared) {
+                results.push(prepared);
+                continue;
+            }
+            if (ignoreMode) {
+                if (!dryRun)
+                    changedIgnoreState = rememberIgnored(prepared, ignoreState) || changedIgnoreState;
+                results.push(ignoreResult(prepared, dryRun ? 'would record permanent ignore' : `recorded in ~/.crouter/${IGNORE_FILE}`, dryRun));
+                continue;
+            }
+            if (isIgnored(prepared, ignoreState)) {
+                if (includeIgnored)
+                    results.push(ignoreResult(prepared, `matched ~/.crouter/${IGNORE_FILE}`, false));
+                continue;
+            }
+            results.push(await convertPrepared(client, prepared, { dryRun, overwrite }));
+        }
+        if (changedIgnoreState)
+            writeIgnoreState(ignoreState);
+        return { results, ignoreFile: ignoreFilePath(), ignoreMode };
+    },
+    render: (result) => renderSummary(result.results, result.ignoreMode === true),
+});

package/dist/commands/sys/sync.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../../core/command.js';
+export declare const sysSyncBranch: BranchDef;

package/dist/commands/sys/sync.js

@@ -0,0 +1,17 @@
+// `crtr sys sync` — the migration branch: three independent, one-way
+// conversion lanes from non-crouter guidance surfaces into documents. See each child leaf for its exact source/target/effects contract.
+import { defineBranch } from '../../core/command.js';
+import { sysSyncSkillsLeaf } from './sync-skills.js';
+import { sysSyncProjectGuidanceLeaf } from './sync-project-guidance.js';
+import { sysSyncDepsLeaf } from './sync-deps.js';
+export const sysSyncBranch = defineBranch({
+    name: 'sync',
+    description: 'migrate non-crouter guidance surfaces into documents',
+    whenToUse: 'importing or migrating an external guidance source — host Agent Skill bundles, project CLAUDE.md/AGENTS.md/.claude/rules, or npm-dependency-shipped Agent Skill bundles — into documents',
+    help: {
+        name: 'sys sync',
+        summary: 'migrate external guidance sources into documents',
+        model: "Three independent one-way conversion lanes, none of which ever export documents back to their source: skills imports host-native SKILL.md bundles as documents owned by you or by the working directory's repo; project-guidance migrates a repo's own CLAUDE.md/AGENTS.md/.claude/rules into documents owned by that repo; deps vendors Agent Skill bundles shipped inside installed npm dependencies as the repo's `deps/…` documents, rewritten on every run.",
+    },
+    children: [sysSyncSkillsLeaf, sysSyncProjectGuidanceLeaf, sysSyncDepsLeaf],
+});

package/dist/commands/sys/terminal-option.d.ts

@@ -0,0 +1,112 @@
+export type TerminalId = 'terminal-app' | 'iterm2' | 'ghostty' | 'vscode' | 'cursor' | 'wezterm' | 'kitty' | 'alacritty' | 'unknown';
+export interface DetectedTerminal {
+    readonly id: TerminalId;
+    readonly name: string;
+}
+/** True positive identification of the terminal the user is typing into, from the
+ *  variables terminals export. `TERM_PROGRAM` is overwritten by tmux (`tmux`), so
+ *  terminal-specific markers are consulted after it. */
+export declare function detectTerminal(env: NodeJS.ProcessEnv): DetectedTerminal;
+/** One safe, previewable write. `lines` is EXACTLY what lands in the file. */
+export interface TerminalConfigEdit {
+    readonly kind: 'append-lines' | 'jsonc-insert-property';
+    readonly path: string;
+    readonly lines: readonly string[];
+    /** Ghostty only: the default config files in load order, so applying can
+     *  re-check (against the files as they are then) that the appended line will be
+     *  the effective one. */
+    readonly ghosttyPaths?: readonly string[];
+    /** Where a running terminal picks the change up. */
+    readonly reload: string;
+}
+export type OptionAsAltStatus = 'configured' | 'unverified' | 'needs-change';
+export interface OptionAsAltPlan {
+    readonly terminal: DetectedTerminal;
+    readonly status: OptionAsAltStatus;
+    /** One-line verdict shown under the heading. */
+    readonly summary: string;
+    /** How to set it by hand (always present unless already configured). */
+    readonly instructions: readonly string[];
+    /** Present only where crouter can write the setting safely. */
+    readonly edit?: TerminalConfigEdit;
+}
+export interface PlanInput {
+    readonly env: NodeJS.ProcessEnv;
+    readonly platform: NodeJS.Platform;
+    readonly home: string;
+}
+/** Ghostty's default config files in the documented load order (ghostty.org/docs/
+ *  config#file-location) — a later file overrides an earlier one, and every macOS
+ *  Application Support file loads after every XDG file. */
+export declare function ghosttyConfigPaths(env: NodeJS.ProcessEnv, home: string): string[];
+export interface GhosttySetting {
+    /** The effective value; `undefined` when never assigned (or reset to default). */
+    readonly value: string | undefined;
+    /** The file holding the last effective assignment. */
+    readonly source: string | undefined;
+    /** An existing file that could not be read — the answer may be incomplete. */
+    readonly unreadable: readonly string[];
+}
+type ReadText = (path: string) => string | null;
+/** The effective `macos-option-as-alt`, following Ghostty's own precedence: the
+ *  default files load in order (a later file overrides an earlier one, the last
+ *  assignment within a file wins), then every `config-file` include — from any of
+ *  them — loads after ALL of them, in order, so an include overrides every
+ *  default file; includes of includes queue behind. `config-file = ""` clears the
+ *  includes gathered so far, `?path` is an optional include, relative paths are
+ *  relative to the including file, and an empty `macos-option-as-alt =` resets to
+ *  the default. A line with an unrecognised value is rejected by Ghostty and
+ *  ignored here. */
+export declare function resolveGhosttyOptionSetting(paths: readonly string[], home?: string, read?: ReadText): GhosttySetting;
+/** The effective `macos-option-as-alt` across Ghostty's config files (and their
+ *  `config-file` includes). `undefined` when never assigned. */
+export declare function readGhosttyOptionSetting(paths: readonly string[], home?: string): string | undefined;
+/** Would appending `lines` to `target` make `macos-option-as-alt = true` the
+ *  effective setting? Evaluates the files as they are now, with the append
+ *  simulated. When not, `blockedBy` names the overriding file. */
+export declare function appendTakesEffect(paths: readonly string[], target: string, home?: string): {
+    readonly effective: boolean;
+    readonly blockedBy?: string;
+    readonly unreadable: readonly string[];
+};
+export interface TopLevelScan {
+    /** Index of the top-level `{`. */
+    readonly open: number;
+    /** True when the object has no property (the next token is its `}`). */
+    readonly empty: boolean;
+    /** Top-level properties only, last duplicate wins: key → raw value token
+     *  (`true`, `false`, a string literal, or `{`/`[` for a container). */
+    readonly props: ReadonlyMap<string, string>;
+}
+/** Scan JSONC for the properties of the top-level object — comments, strings and
+ *  nesting aware, so a key inside `"[markdown]": {…}` is never seen. `undefined`
+ *  when the first token is not `{`. */
+export declare function scanTopLevelObject(text: string): TopLevelScan | undefined;
+export type VscodePropertyState = 'absent' | 'true' | 'false' | 'other' | 'invalid';
+/** State of the TOP-LEVEL `terminal.integrated.macOptionIsMeta` in a
+ *  settings.json text. `invalid` = no top-level object; `other` = present with a
+ *  non-boolean value. */
+export declare function vscodePropertyState(text: string): VscodePropertyState;
+/** The top-level value of `terminal.integrated.macOptionIsMeta`, or `undefined`
+ *  when it is absent (or not a boolean). */
+export declare function readVscodeOptionSetting(text: string): boolean | undefined;
+/** The whole file for a settings.json that does not exist (or is blank). */
+export declare function freshVscodeSettings(): string;
+/** Insert `"<key>": true` as the first property of the top-level object, leaving
+ *  every other byte (comments, trailing commas, formatting) untouched. A blank
+ *  file becomes a fresh object. Returns `undefined` when the text has no
+ *  recognisable top-level object. */
+export declare function insertVscodeProperty(text: string): string | undefined;
+/** Build the Option-as-Alt plan for this machine. `null` off macOS, where Alt is
+ *  already Alt. */
+export declare function planOptionAsAlt(input: PlanInput): OptionAsAltPlan | null;
+/** The text a write would produce, exactly, for the confirm page. */
+export declare function describeEdit(edit: TerminalConfigEdit): string[];
+export interface ApplyResult {
+    readonly ok: boolean;
+    readonly message: string;
+}
+/** Perform one planned edit against the file as it is NOW (never a stale
+ *  snapshot). Idempotent: an already-configured file is left alone. */
+export declare function applyTerminalEdit(edit: TerminalConfigEdit): ApplyResult;
+export {};