@north-light/crouter 0.3.220 → 0.3.221

package/dist/daemon/api/handlers/profiles.js

@@ -7,7 +7,7 @@
 //   GET    /v1/profiles/:name    resolve one profile by name or id
 //   DELETE /v1/profiles/:name    required-force cascade or detach
 import { assertInstalledKind } from '../../../core/config.js';
-import { createProfile, ensureRootProfile, listProfiles, loadProfileManifest, } from '../../../core/profiles/manifest.js';
+import { assertProfileProjects, createProfile, ensureRootProfile, listProfiles, loadProfileManifest, } from '../../../core/profiles/manifest.js';
 import { requestProfileDeletion } from '../../profile-delete.js';
 import { toProfileDTO } from '../map.js';
 const ROOT_PROFILE_NAME = 'root';
@@ -19,6 +19,12 @@ const ROOT_PROFILE_NAME = 'root';
 function handleEnsure(ctx) {
     const name = ctx.params['name'];
     const req = (ctx.body ?? {});
+    // Shape check runs before the idempotent returns, so a legacy string array
+    // cannot slip through an ensure of root or an existing profile. Existence
+    // and realpath normalization stay create-only, so a valid entry naming a
+    // since-deleted directory still returns the existing profile.
+    if (req.projects !== undefined)
+        assertProfileProjects(req.projects);
     if (name === ROOT_PROFILE_NAME) {
         return { status: 200, body: toProfileDTO(ensureRootProfile()) };
     }

package/dist/daemon/api/map.d.ts

@@ -60,7 +60,8 @@ export declare function toCronRunDTO(r: CronRunRecord): CronRunDTO;
 /** Project a profile-manifest entry into its DTO. `default_dir` (the directory
  *  this profile is pinned as default for) is a reverse lookup not carried on the
  *  entry, so it is left null here — a caller that needs it resolves it
- *  separately. */
+ *  separately. Project entries are cloned: the manifest entry is shared cache
+ *  state, so handing out its objects would let a DTO consumer mutate it. */
 export declare function toProfileDTO(entry: ProfileEntry): ProfileDTO;
 /** Extra daemon-derived review fields whose source is outside the canonical row. */
 export interface ReviewDTOExtras {

package/dist/daemon/api/map.js

@@ -258,12 +258,13 @@ export function toCronRunDTO(r) {
 /** Project a profile-manifest entry into its DTO. `default_dir` (the directory
  *  this profile is pinned as default for) is a reverse lookup not carried on the
  *  entry, so it is left null here — a caller that needs it resolves it
- *  separately. */
+ *  separately. Project entries are cloned: the manifest entry is shared cache
+ *  state, so handing out its objects would let a DTO consumer mutate it. */
 export function toProfileDTO(entry) {
     return {
         id: entry.profileId,
         name: entry.manifest.name,
-        projects: [...entry.manifest.projects],
+        projects: entry.manifest.projects.map((p) => ({ ...p })),
         home: entry.manifest.home,
         paused_at: entry.manifest.paused_at,
         default_kind: entry.manifest.default_kind ?? 'general',

package/dist/daemon/api/server.js

@@ -22,6 +22,7 @@ import { attachRoutes } from './handlers/attach.js';
 import { bashJobRoutes } from './handlers/bash-jobs.js';
 import { brokerOperationRoutes } from './handlers/broker-ops.js';
 import { canvasRoutes } from './handlers/canvas.js';
+import { chatInventoryRoutes } from './handlers/chat-inventory.js';
 import { daemonRoutes } from './handlers/daemon.js';
 import { fileRoutes } from './handlers/files.js';
 import { focusRoutes } from './handlers/focus.js';
@@ -66,6 +67,7 @@ function buildRouter() {
         .registerAll(reviewRoutes)
         .registerAll(reviewCommentRoutes)
         .registerAll(inboxRoutes)
+        .registerAll(chatInventoryRoutes)
         .registerAll(feedbackCommentRoutes);
 }
 /** Is this request an attach upgrade — `GET /v1/nodes/{id}/attach` — and if so,

package/dist/hook-authoring.d.ts

@@ -0,0 +1,75 @@
+export type HookJson = null | boolean | number | string | HookJson[] | {
+    [key: string]: HookJson;
+};
+export type HookPhase = 'before' | 'after' | 'replace';
+export interface HookContext {
+    cwd: string;
+    providedParams: string[];
+}
+interface HookRequestBase {
+    protocolVersion: 1;
+    op: string;
+    command: string[];
+    operationId: string;
+    input: {
+        [key: string]: HookJson;
+    };
+    context: HookContext;
+}
+export interface BeforeHookRequest extends HookRequestBase {
+    phase: 'before';
+}
+export interface AfterHookRequest extends HookRequestBase {
+    phase: 'after';
+    result: HookJson;
+}
+export interface ReplaceHookRequest extends HookRequestBase {
+    phase: 'replace';
+}
+export type HookRequest = BeforeHookRequest | AfterHookRequest | ReplaceHookRequest;
+export interface HookSuccess {
+    protocolVersion: 1;
+    ok: true;
+    result?: HookJson;
+}
+export interface HookError {
+    code: string;
+    message: string;
+    field?: string;
+    next?: string;
+}
+export interface HookFailure {
+    protocolVersion: 1;
+    ok: false;
+    error: HookError;
+}
+export type HookResponse = HookSuccess | HookFailure;
+export type HookHandler = (request: HookRequest) => HookResponse | Promise<HookResponse>;
+export type HookHandlers = Record<string, HookHandler>;
+export interface RunHookExecutableOptions {
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+}
+export interface LocalHookProcessOptions {
+    timeoutMs: number;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    input?: string | Uint8Array;
+}
+export interface LocalHookProcessSuccess {
+    ok: true;
+    stdout: string;
+}
+export type LocalHookProcessResult = LocalHookProcessSuccess | HookFailure;
+export interface ForwardHookOptions {
+    headers?: HeadersInit;
+    bearer?: string;
+    timeoutMs: number;
+    maxResponseBytes: number;
+}
+export declare function hookError(code: string, message: string, details?: Omit<HookError, 'code' | 'message'>): HookFailure;
+export declare function runHookExecutable(handlers: HookHandlers, options?: RunHookExecutableOptions): Promise<void>;
+export declare function runLocalHookProcess(argv: readonly string[], options: LocalHookProcessOptions): Promise<LocalHookProcessResult>;
+export declare function forwardHook(endpoint: string | URL, request: HookRequest, options: ForwardHookOptions): Promise<HookResponse>;
+export {};

package/dist/hook-authoring.js

@@ -0,0 +1,358 @@
+import { spawn } from 'node:child_process';
+import { Console } from 'node:console';
+import { posixProcessGroupSpawnOptions, terminateProcessGroup } from './hook-process.js';
+export function hookError(code, message, details = {}) {
+    return { protocolVersion: 1, ok: false, error: { code, message, ...details } };
+}
+export async function runHookExecutable(handlers, options = {}) {
+    const stdin = options.stdin ?? process.stdin;
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    let response;
+    try {
+        const raw = await readStream(stdin);
+        let value;
+        try {
+            value = JSON.parse(raw);
+        }
+        catch {
+            response = hookError('invalid_hook_request', 'stdin must contain one JSON hook request');
+            writeResponse(stdout, response);
+            return;
+        }
+        const request = validateRequest(value);
+        if (!request.valid) {
+            response = hookError('invalid_hook_request', request.message);
+            writeResponse(stdout, response);
+            return;
+        }
+        const handler = handlers[request.value.op];
+        if (handler === undefined) {
+            response = hookError('unsupported_hook_op', `no handler is registered for ${request.value.op}`);
+            writeResponse(stdout, response);
+            return;
+        }
+        try {
+            response = await withConsoleStdoutOnStderr(stderr, () => handler(request.value));
+        }
+        catch (error) {
+            stderr.write(`hook handler ${request.value.op} failed: ${describeError(error)}\n`);
+            response = hookError('hook_handler_failed', `handler failed for ${request.value.op}`);
+        }
+        const validated = validateResponse(response, request.value);
+        if (!validated.valid) {
+            stderr.write(`hook handler ${request.value.op} returned an invalid response: ${validated.message}\n`);
+            response = hookError('invalid_hook_response', validated.message);
+        }
+    }
+    catch (error) {
+        stderr.write(`hook executable failed: ${describeError(error)}\n`);
+        response = hookError('hook_executable_failed', 'hook executable could not read its request');
+    }
+    writeResponse(stdout, response);
+}
+export async function runLocalHookProcess(argv, options) {
+    const executable = argv[0];
+    if (executable === undefined || executable === '') {
+        return hookError('local_process_invalid', 'local process argv[0] must not be empty');
+    }
+    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        return hookError('local_process_invalid_options', 'timeoutMs must be greater than zero');
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        let timedOut = false;
+        let closed = false;
+        let cleanupComplete = false;
+        let timeout;
+        const stdout = [];
+        const settle = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timeout !== undefined)
+                clearTimeout(timeout);
+            resolve(result);
+        };
+        let child;
+        try {
+            child = spawn(executable, argv.slice(1), {
+                cwd: options.cwd,
+                env: options.env,
+                shell: false,
+                stdio: [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'inherit'],
+                ...posixProcessGroupSpawnOptions(),
+            });
+        }
+        catch (error) {
+            settle(hookError('local_process_spawn_failed', `could not start ${executable}: ${describeError(error)}`));
+            return;
+        }
+        const settleTimeout = () => {
+            if (timedOut && closed && cleanupComplete) {
+                settle(hookError('local_process_timeout', `${executable} did not finish within ${options.timeoutMs}ms`));
+            }
+        };
+        timeout = setTimeout(() => {
+            timedOut = true;
+            void terminateProcessGroup(child).then(() => {
+                cleanupComplete = true;
+                settleTimeout();
+            }, (error) => {
+                cleanupComplete = true;
+                settle(hookError('local_process_cleanup_failed', `could not stop ${executable}: ${describeError(error)}`));
+            });
+        }, options.timeoutMs);
+        child.stdout.on('data', (chunk) => stdout.push(chunk));
+        child.once('error', (error) => {
+            if (child.pid !== undefined)
+                return;
+            settle(hookError('local_process_spawn_failed', `could not start ${executable}: ${describeError(error)}`));
+        });
+        child.once('close', (code, signal) => {
+            closed = true;
+            if (timedOut) {
+                settleTimeout();
+                return;
+            }
+            if (code === 0) {
+                settle({ ok: true, stdout: Buffer.concat(stdout).toString('utf8') });
+                return;
+            }
+            const status = signal === null ? `exit code ${code ?? 'unknown'}` : `signal ${signal}`;
+            settle(hookError('local_process_failed', `${executable} exited with ${status}`));
+        });
+        if (options.input !== undefined && child.stdin !== null) {
+            child.stdin.end(options.input);
+        }
+    });
+}
+export async function forwardHook(endpoint, request, options) {
+    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
+        return hookError('hook_forward_invalid_options', 'timeoutMs must be greater than zero');
+    }
+    if (!Number.isSafeInteger(options.maxResponseBytes) || options.maxResponseBytes <= 0) {
+        return hookError('hook_forward_invalid_options', 'maxResponseBytes must be a positive integer');
+    }
+    const headers = new Headers(options.headers);
+    if (!headers.has('content-type'))
+        headers.set('content-type', 'application/json');
+    if (options.bearer !== undefined)
+        headers.set('authorization', `Bearer ${options.bearer}`);
+    const controller = new AbortController();
+    let timedOut = false;
+    const timeout = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, options.timeoutMs);
+    try {
+        const response = await fetch(endpoint, {
+            method: 'POST',
+            headers,
+            body: JSON.stringify(request),
+            signal: controller.signal,
+        });
+        const body = await readResponseBody(response, options.maxResponseBytes);
+        let value;
+        try {
+            value = JSON.parse(body);
+        }
+        catch {
+            return hookError('hook_forward_invalid_response', `hook endpoint returned invalid JSON (HTTP ${response.status})`);
+        }
+        // A valid protocol envelope is authoritative regardless of HTTP status.
+        const validated = validateResponse(value, request);
+        if (!validated.valid)
+            return hookError('hook_forward_invalid_response', `${validated.message} (HTTP ${response.status})`);
+        return validated.value;
+    }
+    catch (error) {
+        if (timedOut)
+            return hookError('hook_forward_timeout', `hook endpoint did not respond within ${options.timeoutMs}ms`);
+        if (error instanceof ResponseTooLargeError) {
+            return hookError('hook_forward_response_too_large', `hook endpoint exceeded ${options.maxResponseBytes} response bytes`);
+        }
+        return hookError('hook_forward_failed', `hook endpoint request failed: ${describeError(error)}`);
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+const STDOUT_CONSOLE_METHODS = ['log', 'info', 'debug', 'dir', 'table', 'group', 'groupCollapsed'];
+async function withConsoleStdoutOnStderr(stderr, run) {
+    const redirected = new Console({ stdout: stderr, stderr, colorMode: false });
+    const original = new Map();
+    for (const method of STDOUT_CONSOLE_METHODS) {
+        original.set(method, console[method]);
+        console[method] = redirected[method].bind(redirected);
+    }
+    try {
+        return await run();
+    }
+    finally {
+        for (const method of STDOUT_CONSOLE_METHODS)
+            console[method] = original.get(method);
+    }
+}
+function writeResponse(stdout, response) {
+    stdout.write(`${JSON.stringify(response)}\n`);
+}
+async function readStream(stream) {
+    const chunks = [];
+    for await (const chunk of stream)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    return Buffer.concat(chunks).toString('utf8');
+}
+async function readResponseBody(response, maxBytes) {
+    if (response.body === null)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel();
+                throw new ResponseTooLargeError();
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return new TextDecoder().decode(concatBytes(chunks, total));
+}
+function concatBytes(chunks, total) {
+    const result = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        result.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return result;
+}
+function validateRequest(value) {
+    if (!isRecord(value))
+        return invalid('request must be an object');
+    if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'phase', 'command', 'operationId', 'input', 'context', 'result'])) {
+        return invalid('request contains unknown fields');
+    }
+    if (value['protocolVersion'] !== 1)
+        return invalid('unsupported hook protocol version');
+    if (typeof value['op'] !== 'string' || value['op'] === '')
+        return invalid('op must be a non-empty string');
+    if (!isStringArray(value['command']) || value['command'].length === 0)
+        return invalid('command must be a non-empty string array');
+    if (typeof value['operationId'] !== 'string' || !/^[0-9a-f]{32}$/.test(value['operationId'])) {
+        return invalid('operationId must be a 32-character lowercase hexadecimal string');
+    }
+    if (!isRecord(value['input']) || !isJson(value['input']))
+        return invalid('input must be a JSON object');
+    if (!isContext(value['context']))
+        return invalid('context must contain cwd and providedParams');
+    if (value['phase'] === 'after') {
+        if (!Object.hasOwn(value, 'result') || !isJson(value['result']))
+            return invalid('after requests require a JSON result');
+        return valid({
+            protocolVersion: 1,
+            op: value['op'],
+            phase: 'after',
+            command: value['command'],
+            operationId: value['operationId'],
+            input: value['input'],
+            context: value['context'],
+            result: value['result'],
+        });
+    }
+    if (value['phase'] !== 'before' && value['phase'] !== 'replace')
+        return invalid('phase must be before, after, or replace');
+    if (Object.hasOwn(value, 'result'))
+        return invalid('only after requests may contain result');
+    return valid({
+        protocolVersion: 1,
+        op: value['op'],
+        phase: value['phase'],
+        command: value['command'],
+        operationId: value['operationId'],
+        input: value['input'],
+        context: value['context'],
+    });
+}
+function validateResponse(value, request) {
+    if (!isRecord(value))
+        return invalid('response must be an object');
+    if (value['protocolVersion'] !== 1)
+        return invalid('response has an unsupported hook protocol version');
+    if (value['ok'] === true) {
+        if (!hasOnlyKeys(value, ['protocolVersion', 'ok', 'result']))
+            return invalid('successful response contains unknown fields');
+        const hasResult = Object.hasOwn(value, 'result');
+        if (request.phase === 'replace' && !hasResult)
+            return invalid('replace response requires result');
+        if (request.phase !== 'replace' && hasResult)
+            return invalid('only replace responses may contain result');
+        if (hasResult) {
+            const result = value['result'];
+            if (!isJson(result))
+                return invalid('response result must be JSON');
+            return valid({ protocolVersion: 1, ok: true, result });
+        }
+        return valid({ protocolVersion: 1, ok: true });
+    }
+    if (value['ok'] !== false || !hasOnlyKeys(value, ['protocolVersion', 'ok', 'error'])) {
+        return invalid('response must contain protocolVersion, ok, and error or result');
+    }
+    if (!isHookError(value['error']))
+        return invalid('response error must contain code and message strings');
+    return valid({ protocolVersion: 1, ok: false, error: value['error'] });
+}
+function isContext(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['cwd', 'providedParams'])
+        && typeof value['cwd'] === 'string'
+        && isStringArray(value['providedParams']);
+}
+function isHookError(value) {
+    return isRecord(value)
+        && hasOnlyKeys(value, ['code', 'message', 'field', 'next'])
+        && typeof value['code'] === 'string'
+        && value['code'] !== ''
+        && typeof value['message'] === 'string'
+        && value['message'] !== ''
+        && (value['field'] === undefined || typeof value['field'] === 'string')
+        && (value['next'] === undefined || typeof value['next'] === 'string');
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+function isJson(value) {
+    if (value === null || typeof value === 'boolean' || typeof value === 'string')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (Array.isArray(value))
+        return value.every(isJson);
+    return isRecord(value) && Object.values(value).every(isJson);
+}
+function hasOnlyKeys(value, keys) {
+    return Object.keys(value).every((key) => keys.includes(key));
+}
+function valid(value) {
+    return { valid: true, value };
+}
+function invalid(message) {
+    return { valid: false, message };
+}
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+class ResponseTooLargeError extends Error {
+}

package/dist/hook-process.d.ts

@@ -0,0 +1,7 @@
+import type { ChildProcess } from 'node:child_process';
+export declare const PROCESS_GROUP_KILL_GRACE_MS = 250;
+export declare function posixProcessGroupSpawnOptions(): {
+    detached: true;
+};
+/** Signal the isolated group, then unconditionally reap survivors after grace. */
+export declare function terminateProcessGroup(child: ChildProcess, graceMs?: number): Promise<void>;

package/dist/hook-process.js

@@ -0,0 +1,34 @@
+export const PROCESS_GROUP_KILL_GRACE_MS = 250;
+export function posixProcessGroupSpawnOptions() {
+    if (process.platform === 'win32') {
+        throw new Error('hook process execution requires POSIX process groups');
+    }
+    return { detached: true };
+}
+/** Signal the isolated group, then unconditionally reap survivors after grace. */
+export async function terminateProcessGroup(child, graceMs = PROCESS_GROUP_KILL_GRACE_MS) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    signalProcessGroup(pid, 'SIGTERM');
+    await delay(graceMs);
+    signalProcessGroup(pid, 'SIGKILL');
+}
+function signalProcessGroup(pid, signal) {
+    try {
+        process.kill(-pid, signal);
+    }
+    catch (error) {
+        if (!isMissingProcess(error))
+            throw error;
+    }
+}
+function isMissingProcess(error) {
+    return typeof error === 'object'
+        && error !== null
+        && 'code' in error
+        && error.code === 'ESRCH';
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/index.d.ts

@@ -21,6 +21,8 @@ export type { CrtrError } from './core/errors.js';
 export { nowIso } from './core/fs-utils.js';
 export { validateOperationId, buildEnvelope, operationIdContext, errorClassCodes, serializeEventRecord, errorClassFromError, } from './core/events/index.js';
 export type { BuildEnvelopeInput, ErrorClass, ErrorClassCode, ErrorClassHints, EventComponent, EventEnvelope, EventError, EventField, EventLevel, EventOutcome, OperationId, OperationIdContext, RetryDisposition, } from './core/events/index.js';
+export { forwardHook, hookError, runHookExecutable, runLocalHookProcess } from './hook-authoring.js';
+export type { AfterHookRequest, BeforeHookRequest, ForwardHookOptions, HookContext, HookError, HookFailure, HookHandler, HookHandlers, HookJson, HookPhase, HookRequest, HookResponse, HookSuccess, LocalHookProcessOptions, LocalHookProcessResult, LocalHookProcessSuccess, ReplaceHookRequest, RunHookExecutableOptions, } from './hook-authoring.js';
 export { validateCommandManifest } from './core/command-manifests/manifest.js';
 export type { CommandManifestValidation, ValidatedCommandManifest } from './core/command-manifests/manifest.js';
 export type { CommandManifestIssue, TransportKind } from './core/command-manifests/schema.js';

package/dist/index.js

@@ -41,6 +41,8 @@ export { nowIso } from './core/fs-utils.js';
 // Pure envelope helpers only. Local source binding and canonical append remain
 // internal so package consumers cannot select crouter runtime file paths.
 export { validateOperationId, buildEnvelope, operationIdContext, errorClassCodes, serializeEventRecord, errorClassFromError, } from './core/events/index.js';
+// ── Hook authoring ───────────────────────────────────────────────────────
+export { forwardHook, hookError, runHookExecutable, runLocalHookProcess } from './hook-authoring.js';
 // ── Command-manifest compatibility ───────────────────────────────────────
 export { validateCommandManifest } from './core/command-manifests/manifest.js';
 export { validatePluginBundle } from './core/command-plugins/bundle.js';

package/dist/migrations/002-profile-project-memory.d.ts

@@ -0,0 +1,2 @@
+import type { ProfileManifestMigration } from './types.js';
+export declare const profileProjectMemoryMigration: ProfileManifestMigration;

package/dist/migrations/002-profile-project-memory.js

@@ -0,0 +1,71 @@
+// 002 — profile projects gain an explicit memory value. Historical manifests
+// stored `projects` as bare directory strings; the current contract is
+// `{ path, memory }`, where memory caps automatic boot/workspace-open
+// disclosure from that project's stores.
+//
+// Mapping: a string entry on the root profile becomes `preview` (root is an
+// aggregate identity — it points at everything and should not absorb every
+// project's full corpus), every other profile's string entries become
+// `content` (they were authored as that profile's own working context).
+// Root is classified ONLY by the fixed profile directory id: a manifest
+// `name` is mutable, so `name === 'root'` would misclassify a renamed profile.
+//
+// Mixed manifests converge: already-valid objects pass through byte-identical
+// and only string entries convert. Anything else — a non-array `projects`, a
+// non-string/non-object entry, an object without a path, an unknown memory
+// value — throws naming the file, because a guessed cap silently widens or
+// narrows what every node under that profile is shown.
+import { PROFILE_PROJECT_MEMORY_VALUES } from '../api/dto/profiles.js';
+import { usage } from '../core/errors.js';
+/** Frozen copy of `ROOT_PROFILE_ID` (core/profiles/manifest.ts). Migrations
+ *  stay out of that module's import graph — its readers reject the very
+ *  manifests this lane exists to convert. */
+const ROOT_PROFILE_ID = 'root-00000000';
+function malformed(input, detail) {
+    return usage(`profile manifest cannot be migrated: ${detail}`, {
+        received: input.path,
+        field: 'projects',
+        next: `Fix ${input.path} by hand — every project entry is a string (pre-migration) or {"path": "/abs/dir", "memory": one of ${PROFILE_PROJECT_MEMORY_VALUES.join(', ')}} — then re-run \`crtr sys migrate\`.`,
+    });
+}
+function isMemory(value) {
+    return typeof value === 'string' && PROFILE_PROJECT_MEMORY_VALUES.includes(value);
+}
+export const profileProjectMemoryMigration = {
+    lane: 'profile-manifest',
+    description: 'profile projects carry an explicit memory value',
+    apply(input) {
+        const stored = input.raw['projects'];
+        if (!Array.isArray(stored)) {
+            throw malformed(input, `projects is ${stored === undefined ? 'missing' : typeof stored}, not an array`);
+        }
+        const legacyMemory = input.profileId === ROOT_PROFILE_ID ? 'preview' : 'content';
+        let converted = false;
+        const projects = stored.map((entry) => {
+            if (typeof entry === 'string') {
+                if (entry.trim() === '')
+                    throw malformed(input, 'a project entry is an empty path');
+                converted = true;
+                return { path: entry, memory: legacyMemory };
+            }
+            if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+                throw malformed(input, `a project entry is ${entry === null ? 'null' : typeof entry}`);
+            }
+            const { path, memory } = entry;
+            if (typeof path !== 'string' || path.trim() === '') {
+                throw malformed(input, `a project entry has no path: ${JSON.stringify(entry)}`);
+            }
+            if (!isMemory(memory)) {
+                throw malformed(input, `project ${path} has an unknown memory value: ${JSON.stringify(memory)}`);
+            }
+            // Byte-identical pass-through: an already-valid entry keeps whatever
+            // else it carries, so re-running plans no change.
+            return entry;
+        });
+        if (!converted)
+            return null;
+        // Spread preserves the manifest's stored key order, so the rewrite's diff
+        // is the projects array and nothing else.
+        return { ...input.raw, projects };
+    },
+};

package/dist/migrations/profile-manifests.d.ts

@@ -0,0 +1,30 @@
+import type { ProfileManifestSnapshot, StateMigration } from './types.js';
+export interface ProfileManifestRunResult {
+    /** Profile manifests found under the profiles root. */
+    profiles: number;
+    /** One row per migration that rewrote a manifest, in registry order. */
+    applied: {
+        profileId: string;
+        path: string;
+        migration: string;
+    }[];
+    /** Post-migration manifest per readable profile, in scan order — coherent
+     *  under `dryRun`, where the same fold ran but nothing was written. */
+    snapshots: ProfileManifestSnapshot[];
+    /** Manifests left untouched because they are not valid JSON. Unreadable
+     *  bytes are not a structure this lane can convert, and failing the run over
+     *  one would block every other profile's convergence. */
+    skipped: {
+        profileId: string;
+        path: string;
+        error: string;
+    }[];
+}
+export declare function runProfileManifestMigrations(profilesRoot: string, opts: {
+    /** Held for the whole re-read/fold/write of one manifest — the same lock
+     *  add/remove take, so a concurrent mutation either lands before the
+     *  re-read or serializes after the write, never under it. */
+    withLock: <T>(profileId: string, fn: () => T) => T;
+    dryRun?: boolean;
+    migrations?: readonly StateMigration[];
+}): ProfileManifestRunResult;