@logicseek/hello-cc 0.1.8 → 1.0.0

package/lib/runtime/buffer-gc.mjs

@@ -0,0 +1,270 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function eligibleBufferStat(stat) {
+  return stat.isFile() || stat.isFIFO();
+}
+
+function objectIdentity(stat) {
+  return `${stat.dev}:${stat.ino}`;
+}
+
+function sameDirectoryObject(left, right) {
+  return left.isDirectory() &&
+    right.isDirectory() &&
+    left.dev === right.dev &&
+    left.ino === right.ino;
+}
+
+function statIdentity(stat) {
+  return {
+    dev: stat.dev,
+    ino: stat.ino,
+    mode: stat.mode,
+    size: stat.size,
+    mtimeMs: stat.mtimeMs,
+    ctimeMs: stat.ctimeMs
+  };
+}
+
+function sameStatIdentity(left, right) {
+  return left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.mode === right.mode &&
+    left.size === right.size &&
+    left.mtimeMs === right.mtimeMs &&
+    left.ctimeMs === right.ctimeMs;
+}
+
+function canonicalEntryPath(value) {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  const resolved = path.resolve(value);
+  const suppliedParent = path.dirname(resolved);
+  try {
+    const suppliedStat = fs.statSync(suppliedParent);
+    const canonicalParent = fs.realpathSync(suppliedParent);
+    const canonicalStat = fs.lstatSync(canonicalParent);
+    if (canonicalStat.isSymbolicLink() || !sameDirectoryObject(suppliedStat, canonicalStat)) return null;
+    return path.join(canonicalParent, path.basename(resolved));
+  } catch {
+    return null;
+  }
+}
+
+function evidenceSnapshot(values) {
+  const paths = new Set();
+  const identities = new Set();
+  for (const value of values || []) {
+    const file = canonicalEntryPath(value);
+    if (!file) continue;
+    paths.add(file);
+    try {
+      const stat = fs.lstatSync(file);
+      if (!stat.isSymbolicLink() && eligibleBufferStat(stat)) identities.add(objectIdentity(stat));
+    } catch {}
+  }
+  return { paths, identities };
+}
+
+export function refreshBufferPlanEvidence(plan, {
+  protectedPaths = [],
+  unknownPaths = [],
+  gcCutoffs = []
+} = {}) {
+  if (!plan || !Array.isArray(plan.deleteEntries)) {
+    throw new TypeError('valid buffer GC plan required');
+  }
+  const protectedEvidence = evidenceSnapshot(protectedPaths);
+  const unknownEvidence = evidenceSnapshot(unknownPaths);
+  const protectedEntries = [];
+  const unknownEntries = [];
+  const deleteEntries = [];
+  for (const entry of plan.deleteEntries) {
+    const identity = `${entry?.stat?.dev}:${entry?.stat?.ino}`;
+    if (protectedEvidence.paths.has(entry.path) || protectedEvidence.identities.has(identity)) {
+      protectedEntries.push(entry);
+    } else if (unknownEvidence.paths.has(entry.path) || unknownEvidence.identities.has(identity)) {
+      unknownEntries.push(entry);
+    } else {
+      deleteEntries.push(entry);
+    }
+  }
+  return {
+    ...plan,
+    evidenceGcCutoffs: [...new Set([
+      ...(plan.evidenceGcCutoffs || []),
+      ...gcCutoffs
+    ])].sort((left, right) => left - right),
+    protectedPaths: protectedEntries.map((entry) => entry.path),
+    unknownPaths: unknownEntries.map((entry) => entry.path),
+    deletePaths: deleteEntries.map((entry) => entry.path),
+    protectedEntries,
+    unknownEntries,
+    deleteEntries
+  };
+}
+
+function canonicalDirectories(values) {
+  const directories = [];
+  const seenPaths = new Set();
+  const seenIdentities = new Set();
+  for (const value of values || []) {
+    if (typeof value !== 'string' || value.length === 0) continue;
+    const resolved = path.resolve(value);
+    let suppliedStat;
+    try { suppliedStat = fs.lstatSync(resolved); } catch { continue; }
+    if (!suppliedStat.isDirectory() || suppliedStat.isSymbolicLink()) continue;
+
+    let directory;
+    let stat;
+    try {
+      directory = fs.realpathSync(resolved);
+      stat = fs.lstatSync(directory);
+    } catch {
+      continue;
+    }
+    if (stat.isSymbolicLink() || !sameDirectoryObject(suppliedStat, stat)) continue;
+    const identity = objectIdentity(stat);
+    if (seenPaths.has(directory) || seenIdentities.has(identity)) continue;
+    seenPaths.add(directory);
+    seenIdentities.add(identity);
+    directories.push({ path: directory, identity });
+  }
+  return directories;
+}
+
+export function planBufferFiles({
+  directories = [],
+  cutoffMs,
+  protectedPaths = [],
+  unknownPaths = [],
+  evidenceGcCutoffs = []
+} = {}) {
+  if (!Number.isFinite(cutoffMs)) throw new TypeError('cutoffMs must be a finite number');
+
+  const protectedEvidence = evidenceSnapshot(protectedPaths);
+  const unknownEvidence = evidenceSnapshot(unknownPaths);
+  const seenIdentities = new Set();
+  const protectedEntries = [];
+  const unknownEntries = [];
+  const deleteEntries = [];
+
+  for (const directory of canonicalDirectories(directories)) {
+    let names;
+    try { names = fs.readdirSync(directory.path); } catch { continue; }
+    for (const name of names) {
+      const file = path.resolve(directory.path, name);
+      if (path.dirname(file) !== directory.path) continue;
+
+      let stat;
+      try { stat = fs.lstatSync(file); } catch { continue; }
+      if (stat.isSymbolicLink() || !eligibleBufferStat(stat) || stat.mtimeMs >= cutoffMs) continue;
+      const identity = objectIdentity(stat);
+      if (seenIdentities.has(identity)) continue;
+      seenIdentities.add(identity);
+
+      const entry = {
+        path: file,
+        stat: statIdentity(stat),
+        directory: { path: directory.path, identity: directory.identity }
+      };
+      if (protectedEvidence.paths.has(file) || protectedEvidence.identities.has(identity)) protectedEntries.push(entry);
+      else if (unknownEvidence.paths.has(file) || unknownEvidence.identities.has(identity)) unknownEntries.push(entry);
+      else deleteEntries.push(entry);
+    }
+  }
+
+  return {
+    cutoffMs,
+    evidenceGcCutoffs: [...evidenceGcCutoffs],
+    protectedPaths: protectedEntries.map((entry) => entry.path),
+    unknownPaths: unknownEntries.map((entry) => entry.path),
+    deletePaths: deleteEntries.map((entry) => entry.path),
+    protectedEntries,
+    unknownEntries,
+    deleteEntries
+  };
+}
+
+export function applyBufferPlan(plan) {
+  if (!plan || !Number.isFinite(plan.cutoffMs) || !Array.isArray(plan.deleteEntries)) {
+    throw new TypeError('valid buffer GC plan required');
+  }
+
+  const result = {
+    deleted: 0,
+    protected: plan.protectedEntries?.length || 0,
+    deferred: plan.unknownEntries?.length || 0
+  };
+
+  for (const entry of plan.deleteEntries) {
+    try {
+      const directory = fs.lstatSync(entry.directory.path);
+      if (directory.isSymbolicLink() ||
+          !directory.isDirectory() ||
+          objectIdentity(directory) !== entry.directory.identity ||
+          fs.realpathSync(entry.directory.path) !== entry.directory.path) {
+        result.deferred += 1;
+        continue;
+      }
+      const current = fs.lstatSync(entry.path);
+      if (current.isSymbolicLink() ||
+          !eligibleBufferStat(current) ||
+          current.mtimeMs >= plan.cutoffMs ||
+          !sameStatIdentity(entry.stat, statIdentity(current))) {
+        result.deferred += 1;
+        continue;
+      }
+      fs.unlinkSync(entry.path);
+      result.deleted += 1;
+    } catch {
+      result.deferred += 1;
+    }
+  }
+  return result;
+}
+
+export function bufferPlanGcCutoffs(plan, retentionSec) {
+  if (!plan || !Number.isFinite(plan.cutoffMs)) {
+    throw new TypeError('valid buffer GC plan required');
+  }
+  if (!Number.isSafeInteger(retentionSec) || retentionSec < 0) {
+    throw new TypeError('retentionSec must be a non-negative safe integer');
+  }
+  const entryCutoffs = plan.deleteEntries.map((entry) => {
+    const boundary = Math.max(0, Math.floor(Number(entry?.stat?.mtimeMs) / 1000) + retentionSec);
+    if (!Number.isSafeInteger(boundary)) {
+      throw new TypeError('buffer GC boundary must be a non-negative safe integer');
+    }
+    return boundary;
+  });
+  const evidenceCutoffs = plan.evidenceGcCutoffs || [];
+  if (!Array.isArray(evidenceCutoffs) || evidenceCutoffs.some((cutoff) =>
+    !Number.isSafeInteger(cutoff) || cutoff < 0)) {
+    throw new TypeError('buffer evidence GC cutoffs must be non-negative safe integers');
+  }
+  return [...new Set([...entryCutoffs, ...evidenceCutoffs])].sort((left, right) => left - right);
+}
+
+export function deferBufferPlan(plan) {
+  if (!plan || !Array.isArray(plan.deleteEntries)) {
+    throw new TypeError('valid buffer GC plan required');
+  }
+  return {
+    deleted: 0,
+    protected: plan.protectedEntries?.length || 0,
+    deferred: (plan.unknownEntries?.length || 0) + plan.deleteEntries.length
+  };
+}
+
+export function pruneBufferFiles(options = {}) {
+  const plan = planBufferFiles(options);
+  if (options.dryRun) {
+    return {
+      deleted: plan.deleteEntries.length,
+      protected: plan.protectedEntries.length,
+      deferred: plan.unknownEntries.length
+    };
+  }
+  return applyBufferPlan(plan);
+}

package/lib/runtime/client.mjs

@@ -1,32 +1,76 @@
 import { CliError } from '../shared/errors.mjs';
 import { readRuntime } from './state.mjs';
-import { runtimeApiUrl } from '../web/runtime.mjs';
+import { runtimeApiUrl, runtimeHttpRequest } from '../web/runtime.mjs';
+import { withRuntimeApiVersionHeader } from '../web/api-version.mjs';
 
 const DEFAULT_CLI_NAME = 'hcc';
 
+function requestAbortScope(signal, timeoutMs) {
+  const controller = new AbortController();
+  const forwardAbort = () => controller.abort(signal?.reason);
+  if (signal?.aborted) forwardAbort();
+  else signal?.addEventListener('abort', forwardAbort, { once: true });
+
+  const timeout = Number(timeoutMs);
+  const timer = Number.isFinite(timeout) && timeout >= 0
+    ? setTimeout(() => controller.abort(new Error('runtime request deadline exceeded')), timeout)
+    : null;
+  return {
+    signal: controller.signal,
+    cleanup() {
+      if (timer) clearTimeout(timer);
+      signal?.removeEventListener('abort', forwardAbort);
+    }
+  };
+}
+
+function waitForAbort(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(signal.reason || new Error('runtime request aborted'));
+  return new Promise((resolve, reject) => {
+    const abort = () => reject(signal.reason || new Error('runtime request aborted'));
+    signal.addEventListener('abort', abort, { once: true });
+    Promise.resolve(promise).then(
+      (value) => {
+        signal.removeEventListener('abort', abort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener('abort', abort);
+        reject(error);
+      }
+    );
+  });
+}
+
 export async function runtimeRequest(ctx, method, route, body = null, runtime = null, opts = {}) {
   const cliName = opts.cliName || DEFAULT_CLI_NAME;
-  const rt = runtime || readRuntime(ctx, { cliName });
+  const rt = runtime || readRuntime(ctx, { cliName, localOnly: Boolean(opts.localOnly) });
   const url = runtimeApiUrl(rt, route);
-  const headers = { 'Content-Type': 'application/json' };
+  const headers = withRuntimeApiVersionHeader({ 'Content-Type': 'application/json' });
   headers['X-HCC-Root'] = ctx.root;
   headers['X-HCC-DB'] = ctx.dbPath;
   if (rt.token) headers.Authorization = `Bearer ${rt.token}`;
   let res;
+  let text;
+  const abortScope = requestAbortScope(opts.signal, opts.timeoutMs);
   try {
-    res = await fetch(url, {
+    res = await waitForAbort(runtimeHttpRequest(rt, route, {
       method,
       headers,
-      body: body === null ? undefined : JSON.stringify(body)
-    });
+      body: body === null ? null : JSON.stringify(body),
+      signal: abortScope.signal
+    }), abortScope.signal);
+    text = res.text;
   } catch (err) {
     throw new CliError('RUNTIME_UNREACHABLE', `Runtime is not reachable at ${rt.base_url}. Start ${cliName} web again.`, {
       runtime: rt.source || rt.base_url,
       message: err.message
     });
+  } finally {
+    abortScope.cleanup();
   }
   let json = null;
-  const text = await res.text();
   if (text.trim()) {
     try {
       json = JSON.parse(text);
@@ -36,7 +80,16 @@ export async function runtimeRequest(ctx, method, route, body = null, runtime =
   }
   if (!res.ok) {
     const error = json && json.error ? json.error : { code: 'RUNTIME_ERROR', message: `Runtime request failed: ${res.status}` };
-    throw new CliError(error.code || 'RUNTIME_ERROR', error.message || `Runtime request failed: ${res.status}`, error);
+    throw new CliError(error.code || 'RUNTIME_ERROR', error.message || `Runtime request failed: ${res.status}`, {
+      ...error,
+      status: res.status
+    });
   }
   return json || {};
 }
+
+export function runtimeBufferGcUnavailable(error) {
+  return error?.code === 'RUNTIME_UNREACHABLE' ||
+    Number(error?.extra?.status) === 404 ||
+    Number(error?.extra?.status) === 426;
+}

package/lib/runtime/fatal-shutdown.mjs

@@ -0,0 +1,54 @@
+import { redactSecrets } from '../shared/redact.mjs';
+
+function fatalReason(error) {
+  if (error instanceof Error) return redactSecrets(error.message || error.name);
+  if (typeof error === 'string') return redactSecrets(error);
+  return 'fatal runtime error';
+}
+
+export function createFatalShutdownController({
+  cleanup,
+  exit,
+  forceExit,
+  log,
+  schedule = setTimeout,
+  cancel = clearTimeout,
+  timeoutMs = 2_000
+}) {
+  let state = 'idle';
+
+  function safeLog(entry) {
+    try { log(redactSecrets(entry)); } catch {}
+  }
+
+  async function fatal(error) {
+    if (state !== 'idle') {
+      forceExit(1);
+      return;
+    }
+
+    state = 'stopping';
+    const deadline = schedule(() => {
+      state = 'forced';
+      forceExit(1);
+    }, timeoutMs);
+    deadline?.unref?.();
+    safeLog({ code: 'FATAL_RUNTIME_ERROR', error });
+    try {
+      await cleanup(fatalReason(error));
+    } catch (cleanupError) {
+      safeLog({ code: 'FATAL_CLEANUP_ERROR', error: cleanupError });
+    }
+    if (state === 'forced') return;
+    state = 'stopped';
+    let exitReturned = false;
+    try {
+      exit(1);
+      exitReturned = true;
+    } finally {
+      if (exitReturned) cancel(deadline);
+    }
+  }
+
+  return { fatal };
+}

package/lib/runtime/project-path.mjs

@@ -0,0 +1,139 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { CliError } from '../shared/errors.mjs';
+
+function pathIsWithin(parent, candidate) {
+  const relative = path.relative(parent, candidate);
+  return relative !== '' && relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+function projectPathForbidden(message) {
+  return new CliError('PROJECT_PATH_FORBIDDEN', message);
+}
+
+function canonicalProjectRoot(root) {
+  const requested = path.resolve(String(root || ''));
+  try {
+    const canonical = fs.realpathSync(requested);
+    if (!fs.statSync(canonical).isDirectory()) throw new Error('not a directory');
+    return canonical;
+  } catch {
+    throw new CliError('PROJECT_NOT_REGISTERED', `Project root does not exist: ${requested}`);
+  }
+}
+
+function ensureStateDirectory(root, createStateDir) {
+  const stateDir = path.join(root, '.hello-cc');
+  let stateStat;
+  try {
+    stateStat = fs.lstatSync(stateDir);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw projectPathForbidden(`Cannot inspect project state directory: ${stateDir}`);
+    }
+    if (!createStateDir) return { stateDir, exists: false };
+    try {
+      fs.mkdirSync(stateDir, { mode: 0o700 });
+      stateStat = fs.lstatSync(stateDir);
+    } catch {
+      throw projectPathForbidden(`Cannot create project state directory: ${stateDir}`);
+    }
+  }
+
+  if (stateStat.isSymbolicLink() || !stateStat.isDirectory()) {
+    throw projectPathForbidden(`Project state directory must be a real directory: ${stateDir}`);
+  }
+  try {
+    const canonical = fs.realpathSync(stateDir);
+    if (canonical !== stateDir || !pathIsWithin(root, canonical)) {
+      throw projectPathForbidden(`Project state directory escapes its project root: ${stateDir}`);
+    }
+    return { stateDir: canonical, exists: true };
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw projectPathForbidden(`Cannot resolve project state directory: ${stateDir}`);
+  }
+}
+
+function validateDatabaseParent(stateDir, db) {
+  const parent = path.dirname(db);
+  const relative = path.relative(stateDir, parent);
+  const segments = relative === '' ? [] : relative.split(path.sep);
+  let current = stateDir;
+  for (const segment of segments) {
+    current = path.join(current, segment);
+    let stat;
+    try {
+      stat = fs.lstatSync(current);
+    } catch {
+      throw projectPathForbidden(`Database parent directory does not exist: ${current}`);
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw projectPathForbidden(`Database parent must contain only real directories: ${current}`);
+    }
+  }
+
+  try {
+    const canonicalParent = fs.realpathSync(parent);
+    if (canonicalParent !== stateDir && !pathIsWithin(stateDir, canonicalParent)) {
+      throw projectPathForbidden(`Database parent escapes project state directory: ${parent}`);
+    }
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw projectPathForbidden(`Cannot resolve database parent directory: ${parent}`);
+  }
+}
+
+function validateDatabaseTarget(stateDir, db) {
+  let stat;
+  try {
+    stat = fs.lstatSync(db);
+  } catch (error) {
+    if (error?.code === 'ENOENT') return db;
+    throw projectPathForbidden(`Cannot inspect project database: ${db}`);
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw projectPathForbidden(`Project database must be a regular file: ${db}`);
+  }
+  try {
+    const canonical = fs.realpathSync(db);
+    if (!pathIsWithin(stateDir, canonical)) {
+      throw projectPathForbidden(`Project database escapes project state directory: ${db}`);
+    }
+    return canonical;
+  } catch (error) {
+    if (error instanceof CliError) throw error;
+    throw projectPathForbidden(`Cannot resolve project database: ${db}`);
+  }
+}
+
+export function resolveProjectDatabase({ root, db, createStateDir = false }) {
+  const requestedRoot = path.resolve(String(root || ''));
+  const canonicalRoot = canonicalProjectRoot(requestedRoot);
+  const rawDb = path.resolve(String(db || path.join(requestedRoot, '.hello-cc', 'mesh.db')));
+  let requestedDb = pathIsWithin(requestedRoot, rawDb)
+    ? path.join(canonicalRoot, path.relative(requestedRoot, rawDb))
+    : rawDb;
+  const intendedStateDir = path.join(canonicalRoot, '.hello-cc');
+  if (!pathIsWithin(intendedStateDir, requestedDb)) {
+    try {
+      const canonicalParent = fs.realpathSync(path.dirname(requestedDb));
+      const canonicalCandidate = path.join(canonicalParent, path.basename(requestedDb));
+      if (pathIsWithin(intendedStateDir, canonicalCandidate)) requestedDb = canonicalCandidate;
+    } catch {}
+  }
+  if (!pathIsWithin(intendedStateDir, requestedDb)) {
+    throw projectPathForbidden(`Database path must live under ${intendedStateDir}`);
+  }
+  const state = ensureStateDirectory(canonicalRoot, Boolean(createStateDir));
+  if (!state.exists) {
+    return { root: canonicalRoot, stateDir: state.stateDir, db: requestedDb };
+  }
+
+  validateDatabaseParent(state.stateDir, requestedDb);
+  return {
+    root: canonicalRoot,
+    stateDir: state.stateDir,
+    db: validateDatabaseTarget(state.stateDir, requestedDb)
+  };
+}