@north-light/api 0.3.580 → 0.3.587

package/dist/commands/pkg/plugin.d.ts

@@ -0,0 +1 @@
+export declare const pluginBranch: import("../../core/command.js").BranchDef;

package/dist/commands/pkg/plugin.js

@@ -0,0 +1,14 @@
+import { defineBranch } from '../../core/command.js';
+import { pluginDisable, pluginEnable, pluginInstall, pluginRemove, pluginUpdate, } from './plugin-manage.js';
+import { pluginList, pluginShow } from './plugin-inspect.js';
+export const pluginBranch = defineBranch({
+    name: 'plugin',
+    description: 'install and manage plugins',
+    whenToUse: 'working with individual plugins: install, remove, enable, disable, update, list, or inspect them. Use `pkg market` only for marketplace source registration, refresh, and browsing.',
+    help: {
+        name: 'pkg plugin',
+        summary: 'plugin lifecycle and inspection',
+        model: 'A plugin may contribute documents (its `memory/` folder) and commands. Command plugins declare one transport in plugin.json: exec runs a local executable; http calls a remote endpoint. Install accepts either a source ref or an HTTP endpoint.',
+    },
+    children: [pluginInstall, pluginRemove, pluginEnable, pluginDisable, pluginUpdate, pluginList, pluginShow],
+});

package/dist/commands/pkg/shared.d.ts

@@ -0,0 +1,13 @@
+import type { Scope } from '../../types.js';
+export declare const GIT_URL_RE: RegExp;
+export declare function isGitUrl(arg: string): boolean;
+export declare function resolveInstallScope(scopeInput: string | undefined): Scope;
+/** The one installed copy an enable/disable acts on: the first scope in
+ *  precedence whose plugins dir holds `name`, disabled copies included. Enable
+ *  validates that exact copy before flipping its config, so both share this
+ *  resolution rather than each walking the scopes. */
+export declare function resolvePluginConfigTarget(name: string, scopeInput: string | undefined): {
+    scope: Scope;
+    root: string;
+} | null;
+export declare function setPluginEnabled(input: Record<string, unknown>, enabled: boolean): Promise<Record<string, unknown>>;

package/dist/commands/pkg/shared.js

@@ -0,0 +1,62 @@
+import { join } from 'node:path';
+import { notFound, usage } from '../../core/errors.js';
+import { resolveScopeArg, pluginsDir, projectScopeRoot } from '../../core/scope.js';
+import { updateConfig } from '../../core/config.js';
+import { pathExists } from '../../core/fs-utils.js';
+// Helpers
+export const GIT_URL_RE = /^(https?:\/\/|git@|ssh:\/\/|file:\/\/)/;
+export function isGitUrl(arg) {
+    return GIT_URL_RE.test(arg) || arg.endsWith('.git');
+}
+export function resolveInstallScope(scopeInput) {
+    if (scopeInput !== undefined) {
+        const resolved = resolveScopeArg(scopeInput);
+        if (resolved === 'all' || resolved === 'builtin') {
+            throw usage('scope must be "user" or "project"');
+        }
+        return resolved;
+    }
+    // Default: project if available, else user
+    return projectScopeRoot() !== null ? 'project' : 'user';
+}
+/** The one installed copy an enable/disable acts on: the first scope in
+ *  precedence whose plugins dir holds `name`, disabled copies included. Enable
+ *  validates that exact copy before flipping its config, so both share this
+ *  resolution rather than each walking the scopes. */
+export function resolvePluginConfigTarget(name, scopeInput) {
+    let scopes;
+    if (scopeInput !== undefined) {
+        const resolved = resolveScopeArg(scopeInput);
+        if (resolved === 'builtin')
+            throw usage('cannot enable/disable plugins in builtin scope');
+        scopes = resolved === 'all' ? ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null) : [resolved];
+    }
+    else {
+        scopes = ['project', 'user'].filter((s) => s !== 'project' || projectScopeRoot() !== null);
+    }
+    for (const scope of scopes) {
+        const pDir = pluginsDir(scope);
+        if (pDir === null)
+            continue;
+        const pluginDir = join(pDir, name);
+        if (pathExists(pluginDir))
+            return { scope, root: pluginDir };
+    }
+    return null;
+}
+export async function setPluginEnabled(input, enabled) {
+    const name = input['name'];
+    const target = resolvePluginConfigTarget(name, input['scope']);
+    if (target === null)
+        throw notFound(`plugin not found: ${name}`);
+    await updateConfig(target.scope, (cfg) => {
+        const entry = cfg.plugins[name];
+        if (entry !== undefined) {
+            entry.enabled = enabled;
+        }
+        else {
+            cfg.plugins[name] = { enabled };
+        }
+    });
+    return { name, scope: target.scope, enabled };
+}

package/dist/commands/pkg.d.ts

@@ -0,0 +1,2 @@
+import type { BranchDef } from '../core/command.js';
+export declare function registerPkg(): BranchDef;

package/dist/commands/pkg.js

@@ -0,0 +1,21 @@
+// `crtr pkg` subtree: plugin lifecycle and marketplace source management.
+import { defineBranch } from '../core/command.js';
+import { pkgBrowseLeaf } from './pkg/browse.js';
+import { pluginBranch } from './pkg/plugin.js';
+import { marketBranch } from './pkg/market.js';
+export function registerPkg() {
+    return defineBranch({
+        name: 'pkg',
+        rootEntry: {
+            concept: 'plugins and marketplaces that extend crtr',
+            desc: 'manage plugins and marketplace sources',
+            useWhen: 'installing or browsing plugins and marketplace sources; plugin commands may use local executable or remote HTTP transport',
+        },
+        help: {
+            name: 'pkg',
+            summary: 'manage plugins and marketplace sources',
+            model: 'Marketplaces are configured source catalogs; plugins are installed extensions resolved from those catalogs or direct HTTP endpoints. Browsing searches the configured catalogs without changing source or install state.',
+        },
+        children: [pkgBrowseLeaf, pluginBranch, marketBranch],
+    });
+}

package/dist/commands/profile/daemon-profiles.d.ts

@@ -0,0 +1,13 @@
+import type { ProfileDTO } from '../../api/dto/profiles.js';
+/** Resolve a `--profile` / profile operand against the caller's visible
+ *  profiles: exact id or name, else the closest name (reported on stderr). */
+export declare function resolveProfileViaDaemon(operand: string): Promise<ProfileDTO>;
+/** A `<profiles count=N>` state element — one `<profile_id> — <name>` line per
+ *  profile the daemon lists for the caller. */
+export declare function profilesStateBlock(): Promise<string>;
+/** A `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
+ *  top-level kind the daemon accepts. Sub-kinds (e.g. `audit/security`) are
+ *  offered to their own top-level ancestor by default, and this block has no
+ *  single ancestor to check against, so only a sub-kind available to `*` is
+ *  listed; a create naming a full sub-kind is valid regardless. */
+export declare function kindsStateBlock(): Promise<string>;

package/dist/commands/profile/daemon-profiles.js

@@ -0,0 +1,38 @@
+// Profile and kind reads a CLI leaf makes through the daemon. The daemon lists
+// only the profiles and kinds visible to the caller's principal, so a sandboxed
+// node's CLI never opens the runtime's profile store or launch config itself.
+import { stateBlock } from '../../core/help.js';
+import { matchProfileOperand } from '../../core/profiles/manifest.js';
+import { localClient } from '../../api/node-transport.js';
+import { cliClient } from '../api-client.js';
+/** Help never starts the daemon: with it stopped, the state element is omitted. */
+const helpClient = () => localClient({ autostart: false });
+const profileKey = (p) => ({ profileId: p.id, name: p.name });
+/** Resolve a `--profile` / profile operand against the caller's visible
+ *  profiles: exact id or name, else the closest name (reported on stderr). */
+export async function resolveProfileViaDaemon(operand) {
+    return matchProfileOperand(await cliClient().listProfiles(), operand, profileKey);
+}
+/** A `<profiles count=N>` state element — one `<profile_id> — <name>` line per
+ *  profile the daemon lists for the caller. */
+export async function profilesStateBlock() {
+    const all = await helpClient().listProfiles();
+    const limit = 20;
+    const lines = all.slice(0, limit).map((p) => `${p.id} — ${p.name}`).join('\n');
+    const body = all.length > limit ? `${lines}\n… ${all.length - limit} more; use crtr profile list` : lines;
+    return stateBlock('profiles', { count: all.length }, body);
+}
+/** A `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
+ *  top-level kind the daemon accepts. Sub-kinds (e.g. `audit/security`) are
+ *  offered to their own top-level ancestor by default, and this block has no
+ *  single ancestor to check against, so only a sub-kind available to `*` is
+ *  listed; a create naming a full sub-kind is valid regardless. */
+export async function kindsStateBlock() {
+    const { kinds } = await helpClient().listKinds();
+    const shown = kinds.filter(({ kind, available_to }) => {
+        const slash = kind.indexOf('/');
+        return slash === -1 || (available_to ?? [kind.slice(0, slash)]).includes('*');
+    });
+    const lines = shown.map(({ kind, when_to_use }) => (when_to_use ? `${kind} — ${when_to_use}` : kind)).join('\n');
+    return stateBlock('kinds', { count: shown.length }, lines);
+}

package/dist/commands/profile/default.d.ts

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

package/dist/commands/profile/default.js

@@ -0,0 +1,183 @@
+// `crtr profile default` manages the per-cwd profile-selection pin.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { loadProfileManifest, resolveProfileOperand } from '../../core/profiles/manifest.js';
+import { profileCoversCwd } from '../../core/profiles/select.js';
+import { existsSync } from 'node:fs';
+import { getDefaultProfileId, setDefaultProfileId, clearDefaultProfile, clearMissingDefaultDirs, listDefaultPins, resolveBindingCwd, } from '../../core/profiles/default-binding.js';
+const setLeaf = defineLeaf({
+    name: 'set',
+    description: 'pin a profile as the default for the current directory',
+    whenToUse: 'you want crtr to stop asking which profile to use here and always default to a chosen one — the command form of the startup menu\u2019s `d` action. The profile must already cover this directory (add its purview relationship with `profile project add --dir` first if not).',
+    help: {
+        name: 'profile default set',
+        summary: "pin a profile as the current directory's default, so the startup chooser stops asking",
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr. Must already cover the current directory (be at/above/below it in its project purview); this pin does not change automatic document delivery limits.',
+            },
+        ],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: "The resolved directory the pin was set for." },
+            { name: 'profile_id', type: 'string', required: true, constraint: 'The pinned profile id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The pinned profile name.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'The resulting ambient effect.' },
+        ],
+        outputKind: 'object',
+        effects: ['Writes this directory\'s pin into `~/.crouter/profile-defaults.json`. The next launch here auto-picks this profile with no prompt (override once with `crtr --pick-profile`).'],
+    },
+    run: async (_input) => {
+        const cwd = process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const entry = resolveProfileOperand(_input['profile']);
+        if (!profileCoversCwd(entry, resolved)) {
+            throw new InputError({
+                error: 'not_covered',
+                message: `profile "${entry.manifest.name}" does not cover ${resolved}, so a default pinned here would be ignored.`,
+                next: `Widen its purview first: \`crtr profile project add ${entry.profileId} --dir ${resolved}\`, then re-run this.`,
+            });
+        }
+        await setDefaultProfileId(cwd, entry.profileId);
+        return {
+            dir: resolved,
+            profile_id: entry.profileId,
+            name: entry.manifest.name,
+            follow_up: `Launches here now auto-pick "${entry.manifest.name}".`,
+        };
+    },
+});
+const clearLeaf = defineLeaf({
+    name: 'clear',
+    description: "remove the current directory's default-profile pin",
+    whenToUse: 'you no longer want a fixed default here — go back to the normal startup chooser (MRU / covering menu). No-op if nothing was pinned.',
+    help: {
+        name: 'profile default clear',
+        summary: "remove a directory's default-profile pin — the current directory's, or any path with --dir, or every pin whose directory is gone with --missing",
+        params: [
+            { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Directory whose pin to clear instead of the current one. It need not exist any more — a pin for a deleted directory is addressed by the path it was set with (a symlinked path that still exists resolves to its real path, as `set` stored it).' },
+            { kind: 'flag', name: 'missing', type: 'bool', required: false, constraint: 'Clear every pin whose directory no longer exists on disk, in one write. Used alone.' },
+        ],
+        output: [
+            { name: 'dir', type: 'string', required: false, constraint: 'The resolved directory the pin was cleared for; absent with --missing.' },
+            { name: 'cleared', type: 'boolean', required: true, constraint: 'True when a pin existed and was removed; false when nothing was pinned.' },
+            { name: 'cleared_dirs', type: 'array', required: false, constraint: 'With --missing: each removed pin as {dir, profile_id}.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Deletes the directory\'s pin from the user-root profile-defaults state, if present. `--missing` deletes every pin whose directory no longer exists.'],
+    },
+    run: async (_input) => {
+        if (_input['missing'] === true) {
+            if (_input['dir'] !== undefined)
+                throw new InputError({ error: 'missing_not_exclusive', message: '--missing cannot be combined with --dir', field: 'missing', next: 'Pass --missing alone.' });
+            const removed = await clearMissingDefaultDirs();
+            return { cleared: removed.length > 0, cleared_dirs: removed, follow_up: removed.length > 0 ? `Cleared ${removed.length} pin(s) whose directory no longer exists.` : 'Every pinned directory still exists.' };
+        }
+        const cwd = _input['dir'] ?? process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const had = getDefaultProfileId(cwd) !== null;
+        await clearDefaultProfile(cwd);
+        return {
+            dir: resolved,
+            cleared: had,
+            follow_up: had
+                ? 'The startup chooser will ask again here. Re-pin with `crtr profile default set <profile>`.'
+                : 'Nothing was pinned here.',
+        };
+    },
+});
+const showLeaf = defineLeaf({
+    name: 'show',
+    description: "show the current directory's default-profile pin",
+    whenToUse: "you want to know which profile (if any) is pinned as this directory's default.",
+    help: {
+        name: 'profile default show',
+        summary: "report the current directory's pinned default profile, or none; --dir asks about another path",
+        params: [
+            { kind: 'flag', name: 'dir', type: 'string', required: false, constraint: 'Directory whose pin to report instead of the current one. It need not exist any more — a pin for a deleted directory is addressed by the path it was set with (a symlinked path that still exists resolves to its real path, as `set` stored it).' },
+        ],
+        output: [
+            { name: 'dir', type: 'string', required: true, constraint: 'The resolved directory queried.' },
+            { name: 'pinned', type: 'boolean', required: true, constraint: 'True when a default is pinned here.' },
+            { name: 'profile_id', type: 'string', required: false, constraint: 'The pinned profile id, when pinned.' },
+            { name: 'name', type: 'string', required: false, constraint: 'The pinned profile name, when it still resolves.' },
+            { name: 'stale', type: 'boolean', required: false, constraint: 'True when a pin exists but its profile no longer resolves (deleted); the selector will self-heal it on next launch.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only.'],
+    },
+    run: async (_input) => {
+        const cwd = _input['dir'] ?? process.cwd();
+        const resolved = resolveBindingCwd(cwd);
+        const id = getDefaultProfileId(cwd);
+        if (id === null) {
+            return {
+                dir: resolved,
+                pinned: false,
+                follow_up: 'Pin one with `crtr profile default set <profile>`.',
+            };
+        }
+        let name;
+        try {
+            name = loadProfileManifest(id).manifest.name;
+        }
+        catch {
+            name = undefined;
+        }
+        return {
+            dir: resolved,
+            pinned: true,
+            profile_id: id,
+            ...(name !== undefined ? { name } : { stale: true }),
+            follow_up: name !== undefined
+                ? 'Change it with `crtr profile default set <profile>`, or clear it with `crtr profile default clear`.'
+                : 'This profile no longer exists; clear the stale pin with `crtr profile default clear`.',
+        };
+    },
+});
+const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'list every directory pinned to a default profile',
+    whenToUse: 'you want to see all default-profile pins at once — including pins for directories that no longer exist — before clearing stale ones with `profile default clear --dir <path>` or `--missing`.',
+    help: {
+        name: 'profile default list',
+        summary: 'every directory → default profile pin, with whether the directory and the profile still exist',
+        params: [],
+        output: [
+            { name: 'pins', type: 'array', required: true, constraint: 'Each pin as {dir, profile_id, name?, dir_exists, profile_exists}, sorted by dir.' },
+        ],
+        outputKind: 'object',
+        effects: ['Read-only.'],
+    },
+    run: async () => ({ pins: listDefaultPins().map((pin) => {
+            let name;
+            try {
+                name = loadProfileManifest(pin.profileId).manifest.name;
+            }
+            catch {
+                name = undefined;
+            }
+            return { dir: pin.dir, profile_id: pin.profileId, ...(name !== undefined ? { name } : {}), dir_exists: existsSync(pin.dir), profile_exists: name !== undefined };
+        }) }),
+    render: (r) => {
+        const pins = r['pins'];
+        if (pins.length === 0)
+            return 'No default-profile pins.';
+        return pins.map((p) => `${p.dir} → ${p.name ?? p.profile_id}${p.dir_exists ? '' : ' [directory missing]'}${p.profile_exists ? '' : ' [profile missing]'}`).join('\n');
+    },
+});
+export const defaultBranch = defineBranch({
+    name: 'default',
+    description: "manage this directory's default-profile pin",
+    whenToUse: "setting, clearing, or inspecting which profile a directory defaults to at startup — so crtr stops asking. Directory-scoped, independent of project purview and automatic document delivery limits.",
+    help: {
+        name: 'profile default',
+        summary: "the per-directory default profile — pin one so the startup chooser stops asking",
+        model: "A pin binds the CURRENT directory to a profile: launches here auto-pick it with no prompt (`crtr --pick-profile` reopens the chooser once). `set` pins a profile (which must already cover this dir), `clear` removes the pin (`--dir <path>` for another path, even a deleted one; `--missing` for every pin whose directory is gone), `show` reports it (`--dir` too), `list` shows every pin. This is directory-scoped selection, independent of `crtr profile project`: project `path` values govern purview and each `memory` value caps automatic disclosure. The startup menu's `d` action writes the same pin.",
+    },
+    children: [setLeaf, clearLeaf, showLeaf, listLeaf],
+});

package/dist/commands/profile/delete.d.ts

@@ -0,0 +1 @@
+export declare const deleteLeaf: import("../../core/command.js").LeafDef;

package/dist/commands/profile/delete.js

@@ -0,0 +1,66 @@
+import { envNodeId } from '../../shared/env.js';
+import { defineLeaf } from '../../core/command.js';
+import { cliClient, rethrowAsCliError } from '../api-client.js';
+export const deleteLeaf = defineLeaf({
+    name: 'delete',
+    description: 'force-delete a profile and its owned runtime state',
+    whenToUse: 'a profile is no longer needed and you intend either to remove every node and schedule pinned to it, or to preserve that state while detaching the profile identity',
+    help: {
+        name: 'profile delete',
+        summary: 'force-delete a profile and its owned state, or detach that state before removing the profile',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Exact profile id, or a unique manifest name. Deletion never guesses at a near miss — unlike every other profile verb, an unrecognized value fails.',
+            },
+            {
+                kind: 'flag',
+                name: 'force',
+                type: 'bool',
+                required: true,
+                constraint: 'Required confirmation for this irreversible operation.',
+            },
+            {
+                kind: 'flag',
+                name: 'detach',
+                type: 'bool',
+                required: false,
+                constraint: 'Preserve nodes and inbox/review history; clear their profile identity and globalize matching crons before removing the profile.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'The removed profile’s stable id.' },
+            { name: 'name', type: 'string', required: true, constraint: 'The removed profile’s manifest name.' },
+            { name: 'mode', type: 'string', required: true, constraint: '`deleted` for the destructive cascade; `detached` when --detach preserved nodes and history.' },
+            { name: 'nodes', type: 'number', required: true, constraint: 'Nodes hard-deleted or detached.' },
+            { name: 'crons', type: 'number', required: true, constraint: 'Crons deleted or globalized.' },
+            { name: 'tickets', type: 'number', required: true, constraint: 'Originating inbox ticket directories removed; zero in detach mode.' },
+            { name: 'reviews', type: 'number', required: true, constraint: 'Originating daemon review records removed; zero in detach mode.' },
+            { name: 'default_pins', type: 'number', required: true, constraint: 'Per-directory default profile pins cleared.' },
+            { name: 'accepted', type: 'boolean', required: false, constraint: 'True when the invoking node belongs to the profile and teardown begins after this result settles.' },
+            { name: 'grace_ms', type: 'number', required: false, constraint: 'Acknowledgement grace before an accepted self-deletion begins.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next action.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Always clears every per-directory default pin for the profile, deletes the documents the profile owns (one a live document outside them links to is kept, still owned by the deleted profile, until its last link goes), and removes the profile directory last. Blocks before mutation while any matching node owns an open managed worktree.',
+            'Without --detach: tears down and hard-deletes every node whose profile_id matches, deletes matching or anchored crons and their in-flight runs, and removes originating inbox tickets plus review records. Cross-profile children are preserved.',
+            'With --detach: preserves nodes, conversations, topology, inbox tickets, and reviews; rewrites node profile_id to null, restarts active brokers without the profile, and rewrites matching crons to global scope.',
+        ],
+    },
+    run: async (input) => {
+        const result = await cliClient().deleteProfile(input['profile'], {
+            force: input['force'],
+            detach: input['detach'],
+            caller_node_id: envNodeId() ?? null,
+        }).catch((err) => rethrowAsCliError(err, 'List profiles with `crtr profile list`.'));
+        return {
+            ...result,
+            follow_up: result.accepted === true
+                ? 'The deletion was accepted; this node will stop after its result settles.'
+                : 'Run `crtr profile list` to see remaining profiles.',
+        };
+    },
+});

package/dist/commands/profile/env.d.ts

@@ -0,0 +1,8 @@
+import type { BranchDef } from '../../core/command.js';
+/** Strips exactly one trailing line ending (`\r\n` or `\n`) — the one
+ *  documented byte the piped-value contract trims — and leaves every other
+ *  byte (leading/trailing spaces, tabs, embedded newlines) untouched. A
+ *  single-quoted heredoc (`<<'EOF'`) always appends exactly one such
+ *  terminator; anything beyond that is content the caller wrote on purpose. */
+export declare function stripSingleTrailingLineEnding(raw: string): string;
+export declare const envBranch: BranchDef;

package/dist/commands/profile/env.js

@@ -0,0 +1,188 @@
+// `crtr profile env` — a profile-scoped store of env vars, injected directly
+// into every broker launched under that profile (`buildBrokerEnv`,
+// `core/runtime/spawn-env.ts`), independent of the daemon's own ambient env
+// or any `.envrc`/`.env` a node's cwd carries. Setting a value here IS the
+// consent to cross the spawn boundary — no matching `spawnEnv.allow` entry is
+// needed. Values are write-only from this surface: `set` and `remove` never
+// echo a value back, and `list` reports names only. See
+// `core/profiles/env-store.ts` for the on-disk (0600) store this wraps.
+import { defineLeaf, defineBranch } from '../../core/command.js';
+import { InputError } from '../../core/io.js';
+import { validateEnvVarName } from '../../core/env-name.js';
+import { cliClient } from '../api-client.js';
+import { resolveProfileViaDaemon } from './daemon-profiles.js';
+/** Strips exactly one trailing line ending (`\r\n` or `\n`) — the one
+ *  documented byte the piped-value contract trims — and leaves every other
+ *  byte (leading/trailing spaces, tabs, embedded newlines) untouched. A
+ *  single-quoted heredoc (`<<'EOF'`) always appends exactly one such
+ *  terminator; anything beyond that is content the caller wrote on purpose. */
+export function stripSingleTrailingLineEnding(raw) {
+    if (raw.endsWith('\r\n'))
+        return raw.slice(0, -2);
+    if (raw.endsWith('\n'))
+        return raw.slice(0, -1);
+    return raw;
+}
+function requireValidName(name) {
+    const check = validateEnvVarName(name);
+    if (!check.isValid) {
+        throw new InputError({
+            error: 'invalid_name',
+            message: `invalid --name: ${check.errors.join('; ')}`,
+            field: 'name',
+            received: name,
+            next: 'Use an env-var-shaped name: starts with a letter or underscore, followed by letters, digits, or underscores.',
+        });
+    }
+}
+const setLeaf = defineLeaf({
+    name: 'set',
+    description: 'store one env var for a profile, value piped on stdin',
+    whenToUse: 'a profile needs a credential or config value injected directly into every broker launched under it \u2014 e.g. a HTTP-transport plugin\u2019s `auth-env` token. Setting it here crosses the broker spawn boundary with no separate `spawnEnv.allow` entry required; re-running with the same name overwrites the value.',
+    help: {
+        name: 'profile env set',
+        summary: 'write (or overwrite) one env var in a profile\u2019s 0600 env store',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.',
+            },
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'Env var name. Must start with a letter or underscore, followed by letters, digits, or underscores (e.g. NL_CORE_TOKEN).',
+            },
+            {
+                kind: 'stdin',
+                name: 'value',
+                required: true,
+                constraint: 'The raw value, piped on stdin \u2014 never as an argv value, to keep it out of shell history. Pipe from a single-quoted heredoc (`<<\'EOF\'`) or `echo -n "$VALUE" |` to preserve exact bytes; trailing newline is trimmed.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'created', type: 'boolean', required: true, constraint: 'true when this name was newly added, false when it replaced an existing value.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'The effect on already-running nodes.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Writes {name: value} to the profile\u2019s 0600 environment store, replacing any prior value under the same name.',
+            'Every broker launched under this profile from now on injects this value directly into its process env \u2014 independent of the daemon\u2019s ambient env, no `spawnEnv.allow` entry needed. Already-running brokers keep whatever env they launched with; a running node picks up a new/changed value only on its next revive.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        requireValidName(name);
+        const { id: profileId } = await resolveProfileViaDaemon(input['profile']);
+        const value = stripSingleTrailingLineEnding(input['value'] ?? '');
+        if (value === '') {
+            throw new InputError({
+                error: 'empty_value',
+                message: 'env var value is empty',
+                field: 'value',
+                next: 'Pipe a non-empty value on stdin.',
+            });
+        }
+        const { changed: created } = await cliClient().setProfileEnv(profileId, name, value);
+        return {
+            profile_id: profileId,
+            created,
+            follow_up: 'A running node under this profile picks up the change on its next revive.',
+        };
+    },
+});
+const listLeaf = defineLeaf({
+    name: 'list',
+    description: 'inventory a profile\u2019s stored env var NAMES \u2014 never values',
+    whenToUse: 'you want to know which env vars a profile has set, without exposing any value. Values never leave the 0600 store \u2014 there is no leaf that reads one back.',
+    help: {
+        name: 'profile env list',
+        summary: 'the sorted list of env var names stored for a profile',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'names', type: 'string[]', required: true, constraint: 'Every stored env var name, sorted. Empty when nothing is stored.' },
+            { name: 'count', type: 'int', required: true, constraint: 'names.length.' },
+            { name: 'follow_up', type: 'string', required: true, constraint: 'Concrete next commands.' },
+        ],
+        outputKind: 'object',
+        effects: ['None. Read-only \u2014 and value-blind by construction: this leaf never reads the stored values.'],
+    },
+    run: async (input) => {
+        const { id: profileId } = await resolveProfileViaDaemon(input['profile']);
+        const { names } = await cliClient().listProfileEnv(profileId);
+        return {
+            profile_id: profileId,
+            names,
+            count: names.length,
+            follow_up: names.length > 0
+                ? `Remove one with \`crtr profile env remove ${profileId} --name <name>\`.`
+                : `Set one with \`crtr profile env set ${profileId} --name <name>\`.`,
+        };
+    },
+});
+const removeLeaf = defineLeaf({
+    name: 'remove',
+    description: 'delete one stored env var from a profile',
+    whenToUse: 'an env var a profile owns is no longer needed \u2014 remove it so future brokers launched under this profile stop receiving it. No-op-shaped success (`removed: false`) if it was never set.',
+    help: {
+        name: 'profile env remove',
+        summary: 'delete one env var from a profile\u2019s 0600 env store',
+        params: [
+            {
+                kind: 'positional',
+                name: 'profile',
+                required: true,
+                constraint: 'Profile id or manifest name; a close-enough name resolves to the nearest profile, reported on stderr.',
+            },
+            {
+                kind: 'flag',
+                name: 'name',
+                type: 'string',
+                required: true,
+                constraint: 'Env var name. Must start with a letter or underscore, followed by letters, digits, or underscores (e.g. NL_CORE_TOKEN).',
+            },
+        ],
+        output: [
+            { name: 'profile_id', type: 'string', required: true, constraint: 'Stable directory id.' },
+            { name: 'removed', type: 'boolean', required: true, constraint: 'true when a value existed and was removed; false when nothing was stored under this name.' },
+        ],
+        outputKind: 'object',
+        effects: [
+            'Deletes {name} from the profile\u2019s 0600 environment store, if present.',
+            'Already-running brokers keep whatever env they launched with; a running node stops receiving this value only on its next revive.',
+        ],
+    },
+    run: async (input) => {
+        const name = input['name'];
+        requireValidName(name);
+        const { id: profileId } = await resolveProfileViaDaemon(input['profile']);
+        const { changed: removed } = await cliClient().removeProfileEnv(profileId, name);
+        return {
+            profile_id: profileId,
+            removed,
+        };
+    },
+});
+export const envBranch = defineBranch({
+    name: 'env',
+    description: 'manage a profile-scoped store of env vars injected into its brokers',
+    whenToUse: 'a profile needs a credential or config value available directly to every broker (and thus every node) launched under it \u2014 e.g. a HTTP-transport plugin\u2019s `auth-env` token \u2014 without exporting it into the daemon\u2019s own ambient shell or granting a `spawnEnv.allow` passthrough.',
+    help: {
+        name: 'profile env',
+        summary: 'a profile\u2019s own 0600 store of env vars, injected directly into every broker launched under it',
+        model: 'Values are write-only from this surface: `set` stores one (value piped on stdin, never argv), `remove` deletes one, `list` reports NAMES only \u2014 no leaf ever reads a value back. `buildBrokerEnv` (`core/runtime/spawn-env.ts`) reads the store straight off disk at every broker launch and injects each value directly into that broker\u2019s process env, independent of the daemon\u2019s own ambient env or any `.envrc`/`.env` a node\u2019s cwd carries. Setting a value here IS the operator\u2019s consent to cross the spawn boundary \u2014 it needs no matching `spawnEnv.allow` entry. A change only reaches an already-running node on its next revive. To set a value for every profile in the calling app, use `crtr sys env set --name <NAME>`.'
+    },
+    children: [setLeaf, listLeaf, removeLeaf],
+});

package/dist/commands/profile/kind.d.ts

@@ -0,0 +1 @@
+export declare const kindLeaf: import("../../core/command.js").LeafDef;