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

package/dist/log.js

@@ -1,156 +0,0 @@
-// packages/core/src/log.js
-import { open, stat } from "node:fs/promises";
-var LEVELS = Object.freeze({ debug: 10, info: 20, warn: 30, error: 40 });
-var REDACTED = "[redacted]";
-var OMITTED = "[omitted]";
-var MAX_STRING = 2e3;
-var MAX_DEPTH = 5;
-var MAX_KEYS = 50;
-var MAX_ITEMS = 20;
-var STACK_LINES = 8;
-var SECRET_KEY = /pass(word|wd)?|secret|token|api[-_]?key|authorization|credential|cookie|private[-_]?key|bearer|signature/i;
-var OMITTED_KEY = /^(env|environment|prompt|prompts|instructions|content|text|input|headers|body|args|argv)$/i;
-var SECRET_NAME = /KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|COOKIE|PRIVATE/i;
-var 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}`]
-];
-function secretValues(env) {
-  const values = /* @__PURE__ */ 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);
-}
-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;
-}
-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") : void 0;
-  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 !== void 0 ? { cause: describeError(error.cause, options) } : {}
-  };
-}
-function redact(value, options = {}, depth = 0, seen = /* @__PURE__ */ new WeakSet()) {
-  if (value === null || value === void 0 || 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 void 0;
-  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;
-}
-var CORRELATION = ["sessionId", "rootId", "assignmentId", "clientMessageId", "requestId", "agent"];
-var stderrSink = (line) => {
-  try {
-    process.stderr.write(`${line}
-`);
-  } catch {
-  }
-};
-function createLogger({ component, level, context = {}, write = stderrSink, now = () => /* @__PURE__ */ 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] !== void 0) record[key] = redact(String(rest[key]), options);
-      if (error !== void 0) {
-        record.error = describeError(error, options);
-        if (!record.code && record.error.code !== void 0) 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 })
-  };
-}
-var TAIL_BYTES = 256 * 1024;
-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");
-    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();
-  }
-}
-export {
-  LEVELS,
-  OMITTED,
-  REDACTED,
-  createLogger,
-  describeError,
-  readLogTail,
-  redact,
-  scrubText
-};

package/dist/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/dist/migrations.js

@@ -1,95 +0,0 @@
-// packages/core/src/migrations.js
-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";
-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((name2) => name2.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}
-`).join(""));
-  }
-}
-var 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 void 0;
-    return {};
-  }
-}
-var exists = (file) => stat(file).then(() => true, () => false);
-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) {
-    await rm(migrationFile(home), { force: true });
-    journal = void 0;
-  }
-  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: (/* @__PURE__ */ new Date()).toISOString() }) + "\n");
-    log?.info(`${resumed ? "continuing" : "running"} state migration ${step.name} (schema ${step.from} \u2192 ${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) {
-        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} \u2192 ${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 = void 0;
-  }
-  if (!info.marked && !steps.length) await writeStateSchema(home, schema, by);
-  return { from: info.schema, to: schema, steps };
-}
-export {
-  MIGRATIONS,
-  migrateState
-};

package/dist/safe-path.d.ts

@@ -1,2 +0,0 @@
-/** Preflight static repository paths. Does not isolate concurrent same-user processes. */
-export function assertNoSymlinks(directory: any, relative: any): Promise<void>;

package/dist/safe-path.js

@@ -1,24 +0,0 @@
-// packages/core/src/safe-path.js
-import { lstat } from "node:fs/promises";
-import path from "node:path";
-import { AlpError } from "./errors.js";
-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}`);
-  }
-}
-export {
-  assertNoSymlinks
-};

package/dist/shell.d.ts

@@ -1,16 +0,0 @@
-/**
- * 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: string, options: import("node:child_process").SpawnOptions): import("child_process").ChildProcess;
-/**
- * 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: import("node:child_process").ChildProcess, name: NodeJS.Signals): void;

package/dist/shell.js

@@ -1,22 +0,0 @@
-// packages/core/src/shell.js
-import { execFile, spawn } from "node:child_process";
-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 });
-}
-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);
-  }
-}
-export {
-  signalShell,
-  spawnShell
-};

package/dist/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/dist/state-schema.js

@@ -1,54 +0,0 @@
-// packages/core/src/state-schema.js
-import { readdir, readFile, mkdir } from "node:fs/promises";
-import path from "node:path";
-import { AlpError } from "./errors.js";
-import { writeAtomic } from "./atomic.js";
-var STATE_SCHEMA = 2;
-var OLDEST_STATE_SCHEMA = 1;
-var stateDir = (home) => path.join(home, "state");
-var schemaFile = (home) => path.join(stateDir(home), "schema.json");
-var migrationFile = (home) => path.join(stateDir(home), "migration.json");
-var DATA = ["sessions", "timeline", "receipts"];
-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((error2) => {
-        if (error2?.code === "ENOENT") return [];
-        throw error2;
-      });
-      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 } : {} };
-}
-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)`);
-}
-async function writeStateSchema(home, schema, by) {
-  await mkdir(stateDir(home), { recursive: true, mode: 448 });
-  await writeAtomic(schemaFile(home), JSON.stringify({ schema, by, at: (/* @__PURE__ */ new Date()).toISOString() }) + "\n");
-}
-export {
-  OLDEST_STATE_SCHEMA,
-  STATE_SCHEMA,
-  assertStateSupported,
-  migrationFile,
-  readStateSchema,
-  schemaFile,
-  stateDir,
-  writeStateSchema
-};

package/src/atomic.d.ts

@@ -1,2 +0,0 @@
-export function moveFile(from: string, to: string): Promise<void>;
-export function writeAtomic(file: string, body: string | Uint8Array, mode?: number): Promise<void>;

package/src/atomic.js

@@ -1,28 +0,0 @@
-import { randomBytes } from 'node:crypto';
-import { rename, rm, writeFile } from 'node:fs/promises';
-
-/**
- * Moves `from` to `to`. On Windows the move fails with EPERM, EACCES or EBUSY while another
- * process has the target open, such as a client reading it; it is tried again then.
- */
-export async function moveFile(from, to) {
-  for (let attempt = 0; ; attempt++) {
-    try { return await rename(from, to); }
-    catch (error) {
-      if (process.platform !== 'win32' || attempt >= 20 || !['EPERM', 'EACCES', 'EBUSY'].includes(error?.code)) throw error;
-      await new Promise(resolve => setTimeout(resolve, 10 + attempt * 10));
-    }
-  }
-}
-
-/** Writes `file` through a temporary file beside it, so a reader sees the old or the new content. */
-export async function writeAtomic(file, body, mode = 0o600) {
-  const temporary = `${file}.${process.pid}.${randomBytes(4).toString('hex')}.tmp`;
-  try {
-    await writeFile(temporary, body, { mode });
-    await moveFile(temporary, file);
-  } catch (error) {
-    await rm(temporary, { force: true }).catch(() => {});
-    throw error;
-  }
-}

package/src/backup.d.ts

@@ -1,27 +0,0 @@
-export const BACKUP_FORMAT: number;
-export const BACKUP_EXTENSION: string;
-export const STATE_UNITS: string[];
-export const CLEARED_UNITS: string[];
-export const HOME_UNITS: string[];
-export const PROJECT_UNITS: string[];
-export function backupsDir(home: string): string;
-export function knownProjects(home: string): Promise<string[]>;
-export type BackupSummary = { file: string; files: number; bytes: number; projects: string[]; stateSchema: number | null; sessions: number; tasks: number };
-export function createBackup(options: { home: string; out: string; units?: string[]; projects?: string[]; by?: string; kind?: string }): Promise<BackupSummary>;
-export function automaticBackup(home: string, kind: string, options?: { units?: string[]; projects?: string[]; by?: string }): Promise<string>;
-export type BackupContents = { file: string; kind: string; by?: string; createdAt: string; home: string; stateSchema: number | null; units: string[]; projects: string[]; sessions: number; tasks: number; files: number; bytes: number; external: number };
-export function verifyBackup(file: string): Promise<BackupContents>;
-export function recoverInterruptedRestore(home: string): Promise<{ outcome: 'rolled back' | 'completed'; file?: string; safety?: string } | undefined>;
-export type RestoreResult = {
-  file: string;
-  safety?: string;
-  stateSchema: number | null;
-  interrupted?: { outcome: 'rolled back' | 'completed'; file?: string; safety?: string };
-  units: Array<{ area: string; unit: string; present: boolean }>;
-  projects: string[];
-  skipped: Array<{ root: string; reason: string }>;
-  warnings: string[];
-};
-export function restoreBackup(options: { home: string; file: string; projects?: boolean; safety?: boolean; clearLive?: boolean; replaceNewer?: boolean; by?: string; beforeSwap?: (index: number, total: number) => Promise<void> | void }): Promise<RestoreResult>;
-export function readRestoredMarker(home: string): Promise<{ at?: string; from?: string; by?: string } | undefined>;
-export function clearRestoredMarker(home: string): Promise<void>;