@anhlp/alp-core 0.0.0-beta.1 → 0.10.0

package/src/log.js

@@ -1,177 +0,0 @@
-import { open, stat } from 'node:fs/promises';
-
-/**
- * Structured, redacted logging for ALP processes. One JSON object per line, written to stderr
- * unless a sink is given: stdout belongs to command output, `--json` and the ACP stream, so a
- * log line never lands there. A record has `time`, `level`, `component`, an optional error
- * `code`, `msg`, correlation ids (`sessionId`, `rootId`, `assignmentId`, `clientMessageId`,
- * `requestId`, `agent`) and a few extra fields. Logging never throws.
- *
- * Nothing sensitive is logged by default: keys that carry prompts, environments or credentials
- * are replaced, secret-looking values and the values of secret-named environment variables are
- * scrubbed from every string, and long strings are cut.
- */
-
-export const LEVELS = Object.freeze({ debug: 10, info: 20, warn: 30, error: 40 });
-export const REDACTED = '[redacted]';
-export const OMITTED = '[omitted]';
-const MAX_STRING = 2000;
-const MAX_DEPTH = 5;
-const MAX_KEYS = 50;
-const MAX_ITEMS = 20;
-const STACK_LINES = 8;
-
-/** Fields that hold a credential: the value is replaced. */
-const SECRET_KEY = /pass(word|wd)?|secret|token|api[-_]?key|authorization|credential|cookie|private[-_]?key|bearer|signature/i;
-/** Fields that hold user content or the process environment: never logged, not even scrubbed. */
-const OMITTED_KEY = /^(env|environment|prompt|prompts|instructions|content|text|input|headers|body|args|argv)$/i;
-/** Environment variable names whose values are secrets, to find them inside any text. */
-const SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|COOKIE|PRIVATE/i;
-
-const PATTERNS = [
-  [/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]{8,}/gi, `$1 ${REDACTED}`],
-  [/\b(sk|rk|pk)-[A-Za-z0-9_-]{16,}/g, REDACTED],
-  [/\bgh[pousr]_[A-Za-z0-9]{20,}/g, REDACTED],
-  [/\bgithub_pat_[A-Za-z0-9_]{20,}/g, REDACTED],
-  [/\bxox[abprs]-[A-Za-z0-9-]{10,}/g, REDACTED],
-  [/\bAKIA[0-9A-Z]{16}\b/g, REDACTED],
-  [/\bAIza[0-9A-Za-z_-]{30,}/g, REDACTED],
-  [/\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{4,}/g, REDACTED],
-  [/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?(-----END [A-Z ]*PRIVATE KEY-----|$)/g, REDACTED],
-  [/(\b[a-z][a-z0-9+.-]*:\/\/)[^\s/@:]+:[^\s/@]+@/gi, `$1${REDACTED}@`],
-  // NAME=value and NAME: value for names that look like secrets; also JSON "token": "value".
-  [/(\b[\w.-]*(?:key|token|secret|passw(?:or)?d|credential|authorization|cookie)[\w.-]*["']?\s*[=:]\s*)(?:"[^"]{4,}"|'[^']{4,}'|[^\s,;&"']{8,})/gi, `$1${REDACTED}`],
-  // --token value, --api-key value
-  [/(--[\w-]*(?:key|token|secret|passw(?:or)?d|credential)[\w-]*\s+)[^\s-][^\s]*/gi, `$1${REDACTED}`],
-];
-
-/** Values of secret-named variables in `env`, long enough that replacing them is not noise. */
-function secretValues(env) {
-  const values = new Set();
-  for (const [name, value] of Object.entries(env ?? {})) if (typeof value === 'string' && value.length >= 8 && SECRET_NAME.test(name)) values.add(value);
-  return [...values].sort((a, b) => b.length - a.length);
-}
-
-/** `text` without anything that looks like a credential, cut to `max` characters. */
-export function scrubText(text, { env = process.env, max = MAX_STRING } = {}) {
-  let result = String(text);
-  for (const value of secretValues(env)) result = result.split(value).join(REDACTED);
-  for (const [pattern, replacement] of PATTERNS) result = result.replace(pattern, replacement);
-  return result.length > max ? `${result.slice(0, max)}... (${result.length - max} more characters)` : result;
-}
-
-/** An error as a plain, scrubbed object: name, code, message and the top of its stack. */
-export function describeError(error, options = {}) {
-  if (!(error instanceof Error)) return { message: scrubText(error, options) };
-  const stack = typeof error.stack === 'string' ? error.stack.split('\n').slice(0, STACK_LINES).join('\n') : undefined;
-  return {
-    name: error.name,
-    ...(typeof error.code === 'string' || typeof error.code === 'number' ? { code: error.code } : {}),
-    message: scrubText(error.message, options),
-    ...(stack ? { stack: scrubText(stack, options) } : {}),
-    ...(error.cause !== undefined ? { cause: describeError(error.cause, options) } : {}),
-  };
-}
-
-/** A copy of `value` that is safe to write to a log: see the module comment. */
-export function redact(value, options = {}, depth = 0, seen = new WeakSet()) {
-  if (value === null || value === undefined || typeof value === 'boolean' || typeof value === 'number') return value;
-  if (typeof value === 'string') return scrubText(value, options);
-  if (typeof value === 'bigint') return String(value);
-  if (typeof value !== 'object') return undefined;
-  if (value instanceof Error) return describeError(value, options);
-  if (seen.has(value)) return '[circular]';
-  if (depth >= MAX_DEPTH) return '[too deep]';
-  seen.add(value);
-  if (Array.isArray(value)) {
-    const items = value.slice(0, MAX_ITEMS).map(item => redact(item, options, depth + 1, seen));
-    return value.length > MAX_ITEMS ? [...items, `... ${value.length - MAX_ITEMS} more`] : items;
-  }
-  const result = {};
-  for (const [key, item] of Object.entries(value).slice(0, MAX_KEYS)) {
-    result[key] = OMITTED_KEY.test(key) ? OMITTED : SECRET_KEY.test(key) ? REDACTED : redact(item, options, depth + 1, seen);
-  }
-  return result;
-}
-
-/** Fields every record may carry to tie its lines to a session, assignment or request. */
-const CORRELATION = ['sessionId', 'rootId', 'assignmentId', 'clientMessageId', 'requestId', 'agent'];
-
-const stderrSink = line => { try { process.stderr.write(`${line}\n`); } catch {} };
-
-/**
- * A logger for `component` (`alpd`, `store`, `runtime`, `acp`, ...). `level` defaults to
- * ALP_LOG_LEVEL, then `info`. `context` ids are added to every record. `write` receives one
- * serialized line without its newline.
- */
-export function createLogger({ component, level, context = {}, write = stderrSink, now = () => new Date(), env = process.env } = {}) {
-  const threshold = LEVELS[level ?? env.ALP_LOG_LEVEL] ?? LEVELS.info;
-  const options = { env };
-  const emit = (name, message, fields = {}) => {
-    if (LEVELS[name] < threshold) return;
-    try {
-      const { code, error, ...rest } = { ...context, ...fields };
-      const record = {
-        time: now().toISOString(), level: name, component, ...(code ? { code: String(code) } : {}), msg: scrubText(message, options),
-      };
-      for (const key of CORRELATION) if (rest[key] !== undefined) record[key] = redact(String(rest[key]), options);
-      if (error !== undefined) {
-        record.error = describeError(error, options);
-        // An error's own code names the failure when the caller gave none.
-        if (!record.code && record.error.code !== undefined) record.code = String(record.error.code);
-      }
-      for (const [key, value] of Object.entries(rest)) {
-        if (CORRELATION.includes(key)) continue;
-        record[key] = OMITTED_KEY.test(key) ? OMITTED : SECRET_KEY.test(key) ? REDACTED : redact(value, options);
-      }
-      write(JSON.stringify(record));
-    } catch {}
-  };
-  return {
-    component,
-    debug: (message, fields) => emit('debug', message, fields),
-    info: (message, fields) => emit('info', message, fields),
-    warn: (message, fields) => emit('warn', message, fields),
-    error: (message, fields) => emit('error', message, fields),
-    child: (extra = {}, name = component) => createLogger({ component: name, level, context: { ...context, ...extra }, write, now, env }),
-  };
-}
-
-const TAIL_BYTES = 256 * 1024;
-
-/**
- * The records at the end of a log file, oldest first. Lines that are not ALP records (output
- * from before structured logging, a runtime's own stderr) are returned as `{ legacy: text }`
- * with the text scrubbed. A file that is missing gives an empty list.
- */
-export async function readLogTail(file, { bytes = TAIL_BYTES, env = process.env } = {}) {
-  let handle;
-  try {
-    handle = await open(file, 'r');
-    const { size } = await stat(file);
-    const start = Math.max(0, size - bytes);
-    const buffer = Buffer.alloc(size - start);
-    await handle.read(buffer, 0, buffer.length, start);
-    const lines = buffer.toString('utf8').split('\n');
-    // The first line of a tail may be cut.
-    if (start > 0) lines.shift();
-    const records = [];
-    for (const line of lines) {
-      if (!line.trim()) continue;
-      try {
-        const record = JSON.parse(line);
-        if (record && typeof record === 'object' && typeof record.time === 'string' && typeof record.level === 'string' && typeof record.msg === 'string') {
-          records.push(redact(record, { env }));
-          continue;
-        }
-      } catch {}
-      records.push({ legacy: scrubText(line, { env, max: 500 }) });
-    }
-    return records;
-  } catch (error) {
-    if (error?.code === 'ENOENT') return [];
-    throw error;
-  } finally {
-    await handle?.close();
-  }
-}

package/src/migrations.d.ts

@@ -1,9 +0,0 @@
-export type Migration = { from: number; to: number; name: string; run(home: string): Promise<void> };
-export const MIGRATIONS: Migration[];
-export type MigrationResult = { from: number; to: number; steps: Array<{ name: string; from: number; to: number; backup: string; resumed: boolean }> };
-export function migrateState(home: string, options?: {
-  by?: string;
-  migrations?: Migration[];
-  target?: number;
-  log?: { info(message: string, fields?: object): void; warn(message: string, fields?: object): void };
-}): Promise<MigrationResult>;

package/src/migrations.js

@@ -1,111 +0,0 @@
-import { readdir, readFile, rm, stat } from 'node:fs/promises';
-import path from 'node:path';
-import { AlpError } from './errors.js';
-import { writeAtomic } from './atomic.js';
-import { STATE_SCHEMA, assertStateSupported, migrationFile, readStateSchema, stateDir, writeStateSchema } from './state-schema.js';
-import { STATE_UNITS, automaticBackup, restoreBackup } from './backup.js';
-
-/**
- * Versioned migrations of alpd's state (plans/reference/ALPD.md §68). Each step moves the
- * state from one schema to the next and is idempotent: run again over its own partial or
- * complete result it writes the same files. Before a step, the state is saved to a backup
- * and `state/migration.json` names it. Policy:
- *
- * - interrupted (a crash, a kill, a power cut): the next start finds the journal and runs
- *   the step again over what it left, with the same backup;
- * - failed (the step threw): the state is restored from that backup, the journal removed,
- *   and the start fails with STATE_MIGRATION_FAILED; the backup stays.
- *
- * The schema marker is written only after a step completed, and the journal removed last.
- */
-
-/**
- * Schema 1 → 2: every timeline line gets the cursor the store already gives it when reading
- * (a line without a larger cursor than the line before is numbered one past it). Lines that
- * do not parse are kept as they are; the store skips them, as before.
- */
-async function timelineCursors(home) {
-  const directory = path.join(stateDir(home), 'timeline');
-  const names = await readdir(directory).catch(error => { if (error?.code === 'ENOENT') return []; throw error; });
-  for (const name of names.filter(name => name.endsWith('.jsonl'))) {
-    const file = path.join(directory, name);
-    const lines = [];
-    let cursor = 0;
-    let changed = false;
-    for (const line of (await readFile(file, 'utf8')).split('\n')) {
-      if (!line) continue;
-      let envelope;
-      try { envelope = JSON.parse(line); } catch { lines.push(line); continue; }
-      cursor = typeof envelope?.cursor === 'number' && envelope.cursor > cursor ? envelope.cursor : cursor + 1;
-      if (envelope?.cursor === cursor) { lines.push(line); continue; }
-      lines.push(JSON.stringify({ ...envelope, cursor }));
-      changed = true;
-    }
-    if (changed) await writeAtomic(file, lines.map(line => `${line}\n`).join(''));
-  }
-}
-
-/** @type {Array<{ from: number, to: number, name: string, run(home: string): Promise<void> }>} */
-export const MIGRATIONS = [
-  { from: 1, to: 2, name: 'timeline-cursors', run: timelineCursors },
-];
-
-async function readJournal(home) {
-  try { return JSON.parse(await readFile(migrationFile(home), 'utf8')); }
-  catch (error) {
-    if (error?.code === 'ENOENT') return undefined;
-    // A journal cut short says only that a migration was under way: start the step over.
-    return {};
-  }
-}
-
-const exists = file => stat(file).then(() => true, () => false);
-
-/**
- * Brings the state to `target` (the current schema), or refuses a newer one without touching it.
- * Returns the steps it ran; `resumed` marks a step an interruption had left unfinished.
- * @param {string} home
- * @param {{ by?: string, migrations?: typeof MIGRATIONS, target?: number, log?: { info(message: string, fields?: object): void, warn(message: string, fields?: object): void } }} [options]
- */
-export async function migrateState(home, { by = 'alp', migrations = MIGRATIONS, target = STATE_SCHEMA, log } = {}) {
-  const info = assertStateSupported(await readStateSchema(home), home);
-  let journal = await readJournal(home);
-  if (journal && Number.isSafeInteger(journal.to) && journal.to <= info.schema) {
-    // The step completed and only the journal's removal was cut off.
-    await rm(migrationFile(home), { force: true });
-    journal = undefined;
-  }
-  if (info.fresh && !journal) {
-    await writeStateSchema(home, target, by);
-    return { from: target, to: target, steps: [] };
-  }
-  let schema = info.schema;
-  const steps = [];
-  while (schema < target) {
-    const step = migrations.find(candidate => candidate.from === schema);
-    if (!step) throw new AlpError('STATE_MIGRATION_MISSING', `ALP has no migration from state schema ${schema}; the state was not changed`);
-    const resumed = journal?.to === step.to && typeof journal.backup === 'string' && await exists(journal.backup);
-    const backup = resumed ? journal.backup : await automaticBackup(home, `pre-migrate-v${step.from}-v${step.to}`, { units: STATE_UNITS, by });
-    if (!resumed) await writeAtomic(migrationFile(home), JSON.stringify({ from: step.from, to: step.to, name: step.name, backup, by, startedAt: new Date().toISOString() }) + '\n');
-    log?.info(`${resumed ? 'continuing' : 'running'} state migration ${step.name} (schema ${step.from} → ${step.to}); backup ${backup}`, { code: 'ALP_STATE_MIGRATING', from: step.from, to: step.to, migration: step.name, resumed });
-    try {
-      await step.run(home);
-    } catch (error) {
-      try {
-        await restoreBackup({ home, file: backup, projects: false, safety: false, clearLive: false, by });
-      } catch (rollback) {
-        // The journal stays: the next start runs the step again over what is there.
-        throw new AlpError('STATE_MIGRATION_ROLLBACK_FAILED', `state migration ${step.name} failed (${error?.message ?? error}) and putting the state back from ${backup} failed too (${rollback?.message ?? rollback}); the next start tries the migration again. See docs/alp/data-recovery.md`, { cause: error });
-      }
-      await rm(migrationFile(home), { force: true });
-      throw new AlpError('STATE_MIGRATION_FAILED', `state migration ${step.name} (schema ${step.from} → ${step.to}) failed: ${error?.message ?? error}; the state was put back from ${backup} and is unchanged. See docs/alp/data-recovery.md`, { cause: error });
-    }
-    await writeStateSchema(home, step.to, by);
-    await rm(migrationFile(home), { force: true });
-    steps.push({ name: step.name, from: step.from, to: step.to, backup, resumed });
-    schema = step.to;
-    journal = undefined;
-  }
-  if (!info.marked && !steps.length) await writeStateSchema(home, schema, by);
-  return { from: info.schema, to: schema, steps };
-}

package/src/safe-path.js

@@ -1,20 +0,0 @@
-import { lstat } from 'node:fs/promises';
-import path from 'node:path';
-import { AlpError } from './errors.js';
-
-/** Preflight static repository paths. Does not isolate concurrent same-user processes. */
-export async function assertNoSymlinks(directory, relative) {
-  const root = path.resolve(directory);
-  const target = path.resolve(root, relative);
-  const tail = path.relative(root, target);
-  if (tail === '..' || tail.startsWith(`..${path.sep}`) || path.isAbsolute(tail)) {
-    throw new AlpError('UNSAFE_PATH', 'Path escapes its scope');
-  }
-  let current = root;
-  for (const part of ['', ...tail.split(path.sep).filter(Boolean)]) {
-    if (part) current = path.join(current, part);
-    const info = await lstat(current).catch(error => { if (error.code !== 'ENOENT') throw error; });
-    if (!info) return;
-    if (info.isSymbolicLink()) throw new AlpError('UNSAFE_PATH', `Refusing symlink in scoped path: ${current}`);
-  }
-}

package/src/shell.js

@@ -1,28 +0,0 @@
-import { execFile, spawn } from 'node:child_process';
-
-/**
- * Starts `command` through the platform's shell: /bin/sh -c in its own process group, or on
- * Windows cmd.exe /d /s /c with the line quoted whole (cmd strips only the outermost quotes,
- * and Node would otherwise escape the quotes inside it).
- * @param {string} command
- * @param {import('node:child_process').SpawnOptions} options
- */
-export function spawnShell(command, options) {
-  if (process.platform !== 'win32') return spawn('/bin/sh', ['-c', command], { ...options, detached: true });
-  return spawn(process.env.ComSpec ?? 'cmd.exe', ['/d', '/s', '/c', `"${command}"`], { ...options, windowsHide: true, windowsVerbatimArguments: true });
-}
-
-/**
- * Signals a command `spawnShell` started and everything it started. Windows has no signals and
- * cmd.exe's children outlive it, so there the whole tree is ended at once by the first signal
- * and no cleanup runs.
- * @param {import('node:child_process').ChildProcess} child
- * @param {NodeJS.Signals} name
- */
-export function signalShell(child, name) {
-  if (process.platform === 'win32') {
-    if (name === 'SIGTERM') execFile('taskkill.exe', ['/PID', String(child.pid), '/T', '/F'], { windowsHide: true }, () => {});
-    return;
-  }
-  try { process.kill(-child.pid, name); } catch { child.kill(name); }
-}

package/src/state-schema.d.ts

@@ -1,9 +0,0 @@
-export const STATE_SCHEMA: number;
-export const OLDEST_STATE_SCHEMA: number;
-export function stateDir(home: string): string;
-export function schemaFile(home: string): string;
-export function migrationFile(home: string): string;
-export type StateSchemaInfo = { schema: number; fresh: boolean; marked: boolean; by?: string };
-export function readStateSchema(home: string): Promise<StateSchemaInfo>;
-export function assertStateSupported(info: StateSchemaInfo, home: string): StateSchemaInfo;
-export function writeStateSchema(home: string, schema: number, by?: string): Promise<void>;

package/src/state-schema.js

@@ -1,60 +0,0 @@
-import { readdir, readFile, mkdir } from 'node:fs/promises';
-import path from 'node:path';
-import { AlpError } from './errors.js';
-import { writeAtomic } from './atomic.js';
-
-/**
- * The version of alpd's durable state in $ALP_HOME/state (plans/reference/ALPD.md §68).
- * `state/schema.json` names it; a state directory without one holds schema 1, the format
- * every ALP before 0.11 wrote. An ALP that finds a newer schema than it knows refuses to
- * open the state and changes nothing in it; an older one is migrated forward at start.
- *
- * 1: session records, receipts and timelines as of ALPD §66; timeline lines may lack a cursor.
- * 2: every timeline line carries its cursor.
- */
-export const STATE_SCHEMA = 2;
-export const OLDEST_STATE_SCHEMA = 1;
-
-export const stateDir = home => path.join(home, 'state');
-export const schemaFile = home => path.join(stateDir(home), 'schema.json');
-export const migrationFile = home => path.join(stateDir(home), 'migration.json');
-
-/** Directories whose entries mean the state holds data, so a missing marker means schema 1, not a fresh home. */
-const DATA = ['sessions', 'timeline', 'receipts'];
-
-/**
- * What the state directory says about its schema. `fresh` when it holds no data and no marker.
- * An unreadable marker is an error: ALP does not guess which format the data is in.
- * @param {string} home
- * @returns {Promise<{ schema: number, fresh: boolean, marked: boolean, by?: string }>}
- */
-export async function readStateSchema(home) {
-  let text;
-  try { text = await readFile(schemaFile(home), 'utf8'); }
-  catch (error) {
-    if (error?.code !== 'ENOENT') throw error;
-    for (const name of DATA) {
-      const entries = await readdir(path.join(stateDir(home), name)).catch(error => { if (error?.code === 'ENOENT') return []; throw error; });
-      if (entries.some(entry => !entry.endsWith('.tmp'))) return { schema: 1, fresh: false, marked: false };
-    }
-    return { schema: STATE_SCHEMA, fresh: true, marked: false };
-  }
-  let marker;
-  try { marker = JSON.parse(text); } catch {}
-  if (!marker || !Number.isSafeInteger(marker.schema) || marker.schema < 1) {
-    throw new AlpError('STATE_SCHEMA_UNREADABLE', `${schemaFile(home)} does not name a state schema; ALP does not open state whose format it cannot tell. Restore a backup, or put back the file`);
-  }
-  return { schema: marker.schema, fresh: false, marked: true, ...(typeof marker.by === 'string' ? { by: marker.by } : {}) };
-}
-
-/** Refuses state written in a schema this ALP does not know, before anything touches it. */
-export function assertStateSupported(info, home) {
-  if (info.schema <= STATE_SCHEMA) return info;
-  throw new AlpError('STATE_SCHEMA_TOO_NEW', `${stateDir(home)} holds state schema ${info.schema}${info.by ? `, written by ${info.by}` : ''}; this ALP knows schema ${STATE_SCHEMA} at most and leaves it untouched. Run that ALP version or a newer one, or replace it with a backup made for this version: alp restore FILE --replace-newer (docs/alp/data-recovery.md)`);
-}
-
-/** Records the schema the state is now in; written atomically. */
-export async function writeStateSchema(home, schema, by) {
-  await mkdir(stateDir(home), { recursive: true, mode: 0o700 });
-  await writeAtomic(schemaFile(home), JSON.stringify({ schema, by, at: new Date().toISOString() }) + '\n');
-}