@crouter/api 0.3.387 → 0.3.388

package/dist/core/profiles/env-store.js

@@ -0,0 +1,163 @@
+// The profile-owned env store: `<runtime>/secrets/env/<app>/<profileId>` — a 0600
+// map of env-var name -> value a profile owns explicitly. `buildBrokerEnv`
+// (`core/runtime/spawn-env.ts`) reads it straight off disk and injects the
+// values directly into every broker launched under that profile, independent
+// of the daemon's own ambient `process.env` or any `.envrc`/`.env` a node's
+// cwd might carry. Setting a value here IS the consent to cross the spawn
+// boundary — no matching `spawnEnv.allow` entry is needed, because these
+// values never pass through the host-env allowlist in the first place; they
+// are a separate, always-injected source. Never surface a stored VALUE
+// outside this file's own readers — `listProfileEnvNames` returns names only,
+// and no caller should log or echo what `readProfileEnvVars` returns.
+import { existsSync, readFileSync, renameSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { profileSpace } from '../layout.js';
+import { loadExactProfileManifest, withProfileManifestLock } from './manifest.js';
+import { ensureDir } from '../fs-utils.js';
+import { notFound, usage } from '../errors.js';
+/** crtr's own identity/routing env names — reserved so a stored profile value
+ *  can never redirect a broker to a different canvas home/db/socket dir or
+ *  masquerade as its own process identity. `HOME` is reserved alongside the
+ *  `CRTR_*` family because crtr has no independent authoritative scope root
+ *  yet; every path in `core/canvas/paths.ts` ultimately derives from it.
+ *  Enforced at write (`setProfileEnvVar` throws below) AND defensively at
+ *  read (`readStoreUnlocked`, which every reader — list/set/remove/inject —
+ *  goes through), so even a reserved name that reached disk some other way
+ *  (hand-edited file, a pre-reservation write) is uniformly invisible rather
+ *  than trusted. */
+const RESERVED_ENV_PREFIX = 'CRTR_';
+const RESERVED_ENV_EXACT_NAMES = new Set(['HOME']);
+export function isReservedEnvName(name) {
+    return name.startsWith(RESERVED_ENV_PREFIX) || RESERVED_ENV_EXACT_NAMES.has(name);
+}
+/** NUL is the one byte no OS accepts in an env value — Node's own `spawn`
+ *  rejects it synchronously and echoes the full value in the thrown error, so
+ *  it must never reach storage or a spawn call. */
+function hasNulByte(value) {
+    return value.includes('\0');
+}
+function envPath(profileId) {
+    const profile = loadExactProfileManifest(profileId);
+    return profileSpace(profile.manifest.grantee ?? 'app:terminal', profileId).env;
+}
+/** Reads env.json into a null-prototype, sanitized own-property map.
+ *  Null-prototype so a stored name like `__proto__` is a plain own data
+ *  property instead of silently colliding with the inherited accessor on an
+ *  ordinary object (which would make `in`/assignment lie about what's
+ *  actually stored — `created`/`removed` would misreport, and the value
+ *  would never actually persist). Sanitized — dropping any non-string,
+ *  NUL-containing, or reserved-name entry — because this file may have been
+ *  hand-edited or written by a version that predates these guards, and every
+ *  reader (list/set/remove/inject) shares this one function, so a bad
+ *  on-disk entry is uniformly invisible instead of leaking into one path but
+ *  not another. Never throws: a corrupt file degrades to empty, matching the
+ *  prior behavior. */
+function readStoreUnlocked(profileId) {
+    const p = envPath(profileId);
+    const vars = Object.create(null);
+    if (!existsSync(p))
+        return { vars };
+    try {
+        const parsed = JSON.parse(readFileSync(p, 'utf8'));
+        for (const [name, value] of Object.entries(parsed.vars ?? {})) {
+            if (typeof value !== 'string')
+                continue;
+            if (hasNulByte(value))
+                continue;
+            if (isReservedEnvName(name))
+                continue;
+            vars[name] = value;
+        }
+    }
+    catch {
+        // Corrupt/unparseable file: degrade to whatever was sanitized so far
+        // (empty, since the loop above never ran).
+    }
+    return { vars };
+}
+/** Writes env.json directly (never via `fs-utils`' generic writers, which
+ *  have no mode control) so the file is created 0600 from the first byte,
+ *  then `chmodSync`s belt-and-suspenders in case it pre-existed with looser
+ *  permissions — the same shape as `core/secrets.ts`. Atomic via tmp+rename. */
+function writeStoreAtomic(profileId, store) {
+    const p = envPath(profileId);
+    ensureDir(dirname(p));
+    const tmp = `${p}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+    writeFileSync(tmp, JSON.stringify(store, null, 2) + '\n', { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, p);
+}
+function requireProfileExists(profileId) {
+    try {
+        loadExactProfileManifest(profileId);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('profile not found:'))
+            throw notFound(`profile not found: ${profileId}`, { received: profileId });
+        throw error;
+    }
+}
+/** Every stored variable NAME for a profile, sorted. Never returns values. */
+export function listProfileEnvNames(profileId) {
+    return Object.keys(readStoreUnlocked(profileId).vars).sort();
+}
+/** Set one variable, replacing any prior value under the same name. Holds the
+ *  same per-profile lock manifest mutations use (`withProfileManifestLock`),
+ *  so a concurrent `profile delete` can never race a write into an
+ *  about-to-vanish profile dir — whichever runs first wins the lock, and the
+ *  loser either sees `not_found` (delete-then-set) or removes the file right
+ *  back out from under a just-written value (set-then-delete, via
+ *  `deleteProfile`'s recursive rm of the whole profile root). Returns whether
+ *  the name was newly added (`true`) or replaced an existing value (`false`). */
+export function setProfileEnvVar(profileId, name, value) {
+    if (isReservedEnvName(name)) {
+        throw usage(`env var name is reserved by crtr: ${name}`, {
+            received: name,
+            field: 'name',
+            next: 'crtr identity/routing names (CRTR_* and HOME) cannot be stored in a profile env store — a stored value under one of these names could redirect a broker to a different canvas home. Choose a different name.',
+        });
+    }
+    if (hasNulByte(value)) {
+        throw usage('env var value contains a NUL byte, which no OS accepts in an environment variable', {
+            field: 'value',
+            next: 'Remove NUL bytes from the piped value and retry.',
+        });
+    }
+    return withProfileManifestLock(profileId, () => {
+        requireProfileExists(profileId);
+        const store = readStoreUnlocked(profileId);
+        const created = !Object.hasOwn(store.vars, name);
+        store.vars[name] = value;
+        writeStoreAtomic(profileId, store);
+        return created;
+    });
+}
+/** Remove one variable. Returns whether it was present. */
+export function removeProfileEnvVar(profileId, name) {
+    return withProfileManifestLock(profileId, () => {
+        requireProfileExists(profileId);
+        const store = readStoreUnlocked(profileId);
+        if (!Object.hasOwn(store.vars, name))
+            return false;
+        delete store.vars[name];
+        writeStoreAtomic(profileId, store);
+        return true;
+    });
+}
+/** Every stored `{name: value}` for a profile — the ONLY function that
+ *  returns raw values, called exclusively by `buildBrokerEnv`
+ *  (`core/runtime/spawn-env.ts`) to inject them directly into a launched
+ *  broker's env. Never throws: a stale/invalid/deleted profile id is a
+ *  hot-path no-op (mirrors `readRawProfileConfig` in `core/config.ts`),
+ *  because broker-env resolution must never fail a launch over a bad profile
+ *  id. */
+export function readProfileEnvVars(profileId) {
+    if (profileId === null || profileId === '')
+        return {};
+    try {
+        return { ...readStoreUnlocked(profileId).vars };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/core/profiles/fuzzy-match.d.ts

@@ -0,0 +1,19 @@
+/** One candidate offered to the matcher: the durable id plus the mutable name. */
+export interface FuzzyCandidate {
+    readonly profileId: string;
+    readonly name: string;
+}
+export interface FuzzyResult {
+    /** The single profile the needle resolved to, or `null` when nothing was
+     *  close enough or several were equally close. */
+    readonly match: FuzzyCandidate | null;
+    /** Populated only when several profiles tied — the caller reports these so
+     *  the user can disambiguate without running `profile list`. */
+    readonly tied: readonly FuzzyCandidate[];
+}
+/** Resolve a typed operand against the profiles on this host. Returns a single
+ *  match only when it is unambiguously the best one: the strongest tier any
+ *  candidate reached, and within it the single lowest edit distance. A genuine
+ *  tie is reported rather than guessed, because silently running under the
+ *  wrong profile is worse than one more prompt. */
+export declare function fuzzyMatchProfile(operand: string, candidates: readonly FuzzyCandidate[]): FuzzyResult;

package/dist/core/profiles/fuzzy-match.js

@@ -0,0 +1,92 @@
+// Fuzzy matching for a user-TYPED profile operand. Pure — no fs, no manifest
+// reads — so the resolution policy is testable on its own and `manifest.ts`
+// stays the sole owner of path safety and manifest IO.
+//
+// This exists because nobody remembers a profile's exact registered name, let
+// alone its `<slug>-<8hex>` id. `crtr --profile crout` should run the `crouter`
+// profile instead of failing with a list the user then has to read and retype.
+/** Case-, space-, and punctuation-insensitive comparison key. "My Profile",
+ *  "my-profile", and "myprofile" all collapse to the same key, so the common
+ *  near-miss (wrong separator, wrong case) resolves in the first tier. */
+function normalize(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/** The generated id's `-<8 hex>` suffix carries no meaning to a human typing a
+ *  profile, so match against the slug alone as well as the whole id. */
+function idSlug(profileId) {
+    return profileId.replace(/-[0-9a-f]{8}$/, '');
+}
+/** Every string a human might plausibly have been aiming at for one profile. */
+function haystacks(candidate) {
+    const keys = [normalize(candidate.name), normalize(idSlug(candidate.profileId)), normalize(candidate.profileId)];
+    return keys.filter((key, index) => key !== '' && keys.indexOf(key) === index);
+}
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    let previous = Array.from({ length: b.length + 1 }, (_, i) => i);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+            current[j] = Math.min(current[j - 1] + 1, previous[j] + 1, substitution);
+        }
+        previous = current;
+    }
+    return previous[b.length];
+}
+/** Tiers, strongest first. They are ordered by how confidently a human meant
+ *  this profile, NOT by string similarity — a prefix the user stopped typing is
+ *  a stronger signal than a one-character edit that happens to score well. */
+const TIER_NORMALIZED_EQUAL = 0;
+const TIER_PREFIX = 1;
+const TIER_CONTAINS = 2;
+const TIER_TYPO = 3;
+function scoreOne(needle, candidate) {
+    let best = null;
+    for (const hay of haystacks(candidate)) {
+        const distance = levenshtein(needle, hay);
+        let tier = null;
+        if (needle === hay)
+            tier = TIER_NORMALIZED_EQUAL;
+        else if (hay.startsWith(needle))
+            tier = TIER_PREFIX;
+        else if (hay.includes(needle) || needle.includes(hay))
+            tier = TIER_CONTAINS;
+        // A typo budget that scales with length: one edit for a short name, more
+        // for a long one. Without the floor, a 3-character name would tolerate
+        // nothing; without the scaling, two unrelated long names would collide.
+        else if (distance <= Math.max(1, Math.floor(hay.length / 3)))
+            tier = TIER_TYPO;
+        if (tier === null)
+            continue;
+        if (best === null || tier < best.tier || (tier === best.tier && distance < best.distance)) {
+            best = { candidate, tier, distance };
+        }
+    }
+    return best;
+}
+/** Resolve a typed operand against the profiles on this host. Returns a single
+ *  match only when it is unambiguously the best one: the strongest tier any
+ *  candidate reached, and within it the single lowest edit distance. A genuine
+ *  tie is reported rather than guessed, because silently running under the
+ *  wrong profile is worse than one more prompt. */
+export function fuzzyMatchProfile(operand, candidates) {
+    const needle = normalize(operand);
+    if (needle === '')
+        return { match: null, tied: [] };
+    const scored = candidates.map((c) => scoreOne(needle, c)).filter((s) => s !== null);
+    if (scored.length === 0)
+        return { match: null, tied: [] };
+    const bestTier = Math.min(...scored.map((s) => s.tier));
+    const inTier = scored.filter((s) => s.tier === bestTier);
+    const bestDistance = Math.min(...inTier.map((s) => s.distance));
+    const winners = inTier.filter((s) => s.distance === bestDistance);
+    if (winners.length === 1)
+        return { match: winners[0].candidate, tied: [] };
+    return { match: null, tied: winners.map((s) => s.candidate) };
+}

package/dist/core/profiles/manifest.d.ts

@@ -0,0 +1,120 @@
+import type { ProfileManifest } from '../../types.js';
+import type { DeliveryLimits, ProfileProject, ProfileProjectMemory } from '../../api/dto/profiles.js';
+export declare const ROOT_PROFILE_ID = "root-00000000";
+export declare function profileMemoryDir(profileId: string): string;
+export declare function assertProfileProjects(entries: unknown): asserts entries is ProfileProject[];
+export declare function assertDeliveryLimits(value: unknown): asserts value is DeliveryLimits;
+export interface ProfileEntry {
+    profileId: string;
+    manifest: ProfileManifest;
+}
+export interface ProfileEnumeration {
+    entries: ProfileEntry[];
+    unreadableIds: string[];
+}
+export declare function listProfiles(): ProfileEntry[];
+export type ProfileLookup = {
+    kind: 'resolved';
+    entry: ProfileEntry;
+} | {
+    kind: 'absent';
+} | {
+    kind: 'unreadable';
+    profileId: string;
+    manifestPath: string;
+};
+export declare function lookupProfile(profileIdOrName: string): ProfileLookup;
+/** Read one exact profile id without falling back to manifest-name matching.
+ * Used at persistence gates that already hold a resolved durable identity. */
+export declare function loadExactProfileManifest(profileId: string): ProfileEntry;
+/** Exact resolution only: the generated id, else a unique manifest `name`.
+ *  Returns `null` when nothing matches exactly; still THROWS when a name is
+ *  shared by several profiles, because that is a real collision the caller
+ *  cannot resolve by guessing (and fuzzy matching would only guess harder). */
+/** The two facts operand matching reads, from a stored entry or a daemon DTO. */
+export interface ProfileCandidate {
+    profileId: string;
+    name: string;
+}
+type CandidateOf<T> = (entry: T) => ProfileCandidate;
+export declare function loadProfileManifest(profileIdOrName: string): ProfileEntry;
+/** Resolve a profile the USER TYPED — a `--profile` flag or a `<profile>`
+ *  operand. Exact id or name wins outright; only when nothing matches exactly
+ *  does this fall back to fuzzy matching on name and id slug, so a typed
+ *  `crout`, `Crouter`, or `cruoter` reaches the `crouter` profile instead of
+ *  failing with a list the user has to read and retype. A fuzzy hit is
+ *  announced on STDERR (never stdout, which callers pipe) so the user always
+ *  knows which profile actually ran.
+ *
+ *  NEVER call this with a STORED `profile_id` (a node's `meta.profile_id`,
+ *  `CRTR_PROFILE_ID`, a pinned default). A durable id that no longer resolves
+ *  means the profile was deleted — the correct answer there is the not-found
+ *  those callers already handle, not the nearest surviving profile. Use
+ *  `loadProfileManifest` (or `loadExactProfileManifest`) for those. */
+export declare function resolveProfileOperand(operand: string): ProfileEntry;
+/** `resolveProfileOperand` over any candidate list — the CLI passes the
+ *  profiles the daemon lists for its caller. */
+export declare function matchProfileOperand<T>(all: readonly T[], operand: string, key: CandidateOf<T>): T;
+/** Hold the per-profile manifest lock for the duration of `fn`. ALL manifest
+ *  mutations (create/rename/add-project/remove-project/delete/last-used)
+ *  below run inside this. */
+export declare function withProfileManifestLock<T>(profileId: string, fn: () => T): T;
+export declare function ensureRootProfile(): ProfileEntry;
+/** The env name a metadata entry surfaces as (spawn-env source F). Also the
+ *  uniqueness domain for keys: the fold is lossy (`a-b`, `a_b`, `A_B` →
+ *  `CRTR_PROFILE_META_A_B`), so two stored keys may not share a fold. */
+export declare function metadataEnvName(key: string): string;
+/** Reject anything a valid metadata map may not carry. Takes `unknown`
+ *  because the API route hands over a caller-supplied body slice — the
+ *  TypeScript type on the DTO proves nothing at runtime. */
+export declare function assertProfileMetadata(entries: unknown): asserts entries is Record<string, string>;
+/** Drop entries no valid mutation could have written — a manifest is
+ *  hand-editable, so a projection or merge base must never trust it raw.
+ *  Never throws; on an env-name collision the first entry wins (matching
+ *  injection, where a deterministic winner beats insertion-order luck). */
+export declare function sanitizeProfileMetadata(stored: unknown): Record<string, string>;
+export declare function createProfile(name: string, projects?: ProfileProject[], opts?: {
+    defaultKind?: string;
+    metadata?: Record<string, string>;
+    grantee?: string;
+}): ProfileEntry;
+export declare function ensureAppProfile(grantee: string): ProfileEntry;
+export declare function updateProfileLastUsed(profileId: string): ProfileEntry;
+/** Paused check for an ALREADY-RESOLVED durable id (a canvas row's `profile_id`,
+ * `CRTR_PROFILE_ID`) — exact-id only, no name matching, so it costs one small
+ * read on the hot delivery paths that call it every poll. Fails OPEN: an id
+ * whose manifest is missing or corrupt is not paused, because treating it as
+ * paused would strand that node's queued inbox forever. */
+export declare function isProfilePaused(profileId: string | null | undefined): boolean;
+/** One set-based pause read for canvas-wide projections. */
+export declare function pausedCanvasProfiles(): Set<string>;
+/** Refuse a launch under a paused profile, naming the resume command. Shared by
+ * every gate that already holds a loaded manifest. */
+export declare function assertProfileEntryActive(entry: ProfileEntry): void;
+export declare function assertProfileActive(profileId: string | null | undefined): ProfileEntry | null;
+export declare function pauseProfile(profileId: string): ProfileEntry;
+export declare function resumeProfile(profileId: string): ProfileEntry & {
+    pausedAt: string | null;
+};
+export declare function setProfileDefaultKind(profileId: string, defaultKind: string): ProfileEntry;
+/** Merge `set` entries over the stored map and drop `unset` keys; the
+ *  `metadata` field is omitted entirely when the result is empty. */
+export declare function updateProfileMetadata(profileId: string, set: Record<string, string>, unset?: string[]): ProfileEntry;
+/** A profile's stored metadata for broker-env injection — sanitized entry by
+ *  entry (a manifest is hand-editable, so a bad key/value is dropped rather
+ *  than trusted) and never throwing: a stale/invalid/absent profile id is a
+ *  hot-path no-op, because broker-env resolution must never fail a launch
+ *  over a bad profile id (mirrors `readProfileEnvVars`). */
+export declare function readProfileMetadata(profileId: string | null): Record<string, string>;
+/** Change the manifest `name` only. Callers that own the canvas (the daemon's
+ *  `PATCH /v1/profiles/:name`) must also rename the profile's canvas handle —
+ *  use `renameProfileAndHandle` there; the CLI and panels go through that route. */
+export declare function renameProfile(profileId: string, name: string): ProfileEntry;
+/** A new path appends; a path already listed keeps its position. */
+export declare function addProfileProject(profileId: string, dir: string): ProfileEntry;
+/** Set one owner's automatic delivery limit. `content` is the uncapped level,
+ *  so it removes the owner's entry instead of storing it. */
+export declare function setProfileDeliveryLimit(profileId: string, owner: string, level: ProfileProjectMemory): ProfileEntry;
+export declare function removeProfileProject(profileId: string, dir: string): ProfileEntry;
+export declare function deleteProfile(profileId: string): void;
+export {};