@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/settings/shared.js

@@ -0,0 +1,37 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/** Shared redaction rules for settings and their compatibility adapters. */
+const { OFF_WORDS, isOffWord } = require('../off-words.js');
+
+function maskUrlParts(text        )         {
+  return text.split('&').map((part) => {
+    if (part === '') return part;
+    const equalsAt = part.indexOf('=');
+    return equalsAt < 0 ? '***' : `${part.slice(0, equalsAt)}=***`;
+  }).join('&');
+}
+
+/** A URL with query values and user-info redacted, including non-hierarchical endpoint forms. */
+function maskUrl(text        )         {
+  let value = text;
+  try {
+    const url = new URL(text);
+    if (url.username || url.password) value = `${url.protocol}//***@${url.host}${url.pathname}${url.search}${url.hash}`;
+  } catch {
+    // The historical fallback also covers malformed URL-style authorities.
+  }
+  value = value.replace(/\/\/.*@/g, '//***@');
+  value = value.replace(/^([^/:]+:)[^@/]*@/, '$1***@');
+  const hashAt = value.indexOf('#');
+  const beforeHash = hashAt < 0 ? value : value.slice(0, hashAt);
+  const fragment = hashAt < 0 ? '' : `#${maskUrlParts(value.slice(hashAt + 1))}`;
+  const queryAt = beforeHash.indexOf('?');
+  if (queryAt < 0) return `${beforeHash}${fragment}`;
+  const head = beforeHash.slice(0, queryAt + 1);
+  const query = maskUrlParts(beforeHash.slice(queryAt + 1));
+  return `${head}${query}${fragment}`;
+}
+
+module.exports = { OFF_WORDS, isOffWord, maskUrl };

package/src/runtime/settings/worker-billing.js

@@ -0,0 +1,107 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The person-written billing record (`workers.billing`, global-only): which headless workers the
+ * owner states are `free` or `metered`. It lets a capped dispatch (`--billing-cap free`) treat a
+ * worker the registry lists as `unknown` as free, and it can only narrow a worker the registry
+ * lists as `free`. It lives with the settings it reads so dispatch needs no settings internals.
+ */
+
+                                              
+                                                                                     
+                                                                                                                          
+
+const none = (state                        , reason                = null)                => ({ state, reason, workers: {} });
+
+/**
+ * Read fresh on every call (never memoised: a copied env defeats the resolver cache), from the user
+ * layer only: a project file never decides it. Absent is no config home or no decided value. Invalid
+ * is a resolution in the invalid state, any invalid candidate, an id that is not in `workerIds`
+ * (reason `unknown-worker:<id>`) or any thrown error: the caller then counts no worker as free.
+ * A retired harness id (127 IC-005) is dropped by the resolver before this sees the value, with an
+ * advisory in the settings view's notes; it is never an unknown worker. `registry` is an optional
+ * loaded settings registry (tests); it defaults to the shipped one.
+ */
+function readWorkerBilling(env      = process.env, { workerIds = [], registry }                                           = {})                {
+  try {
+    const { loadSettings } = require('./resolve.js');
+    const resolution = loadSettings({ global: true, env: { ...env }, registry }).get('workers.billing', 'global');
+    const bad = resolution.candidates.find((c     ) => c.status === 'invalid');
+    if (bad || resolution.state === 'invalid') return none('invalid', (bad && bad.reason) || 'invalid');
+    if (resolution.origin?.via === 'no-config-home') return none('absent');
+    const value = resolution.value;
+    if (value === null || value === undefined) return none('absent');
+    for (const id of Object.keys(value)) {
+      if (!workerIds.includes(id)) return none('invalid', `unknown-worker:${id}`);
+    }
+    return { state: 'set', reason: null, workers: structuredClone(value) };
+  } catch {
+    return none('invalid', 'unreadable');
+  }
+}
+
+/**
+ * Derives billing category from harness detected authentication mode (IC-004).
+ * subscription -> free, api-key -> metered, unverified -> unknown.
+ */
+function deriveBilling(mode                                                    )          {
+  if (mode === 'subscription') return 'free';
+  if (mode === 'api-key') return 'metered';
+  return 'unknown';
+}
+
+/**
+ * The billing a capped dispatch judges for one worker.
+ * Precedence: user record (`workers.billing`) > derived (`catalogue`) > registry descriptor.
+ * Cap enforcement: neither record nor derived ever lifts a registry `metered`.
+ */
+function effectiveBilling(
+  descriptorBilling         ,
+  harnessId        ,
+  record                      ,
+  catalogue      
+)   
+                 
+                                                 
+                    
+                        
+  {
+  const base          = descriptorBilling === 'free' || descriptorBilling === 'metered' ? descriptorBilling : 'unknown';
+  const entry = record && record.state === 'set' && Object.hasOwn(record.workers, harnessId) ? record.workers[harnessId] : null;
+
+  // 1. User record
+  if (entry) {
+    if (base === 'metered') {
+      return { value: 'metered', source: 'registry' };
+    }
+    if (entry.billing !== base && (entry.billing === 'metered' || base === 'unknown')) {
+      return { value: entry.billing, source: 'user-record', asserted: entry.asserted };
+    }
+    if (entry.billing === base) {
+      return { value: base, source: 'registry' };
+    }
+  }
+
+  // 2. Derived from catalogue
+  if (catalogue && catalogue.harnesses && Object.hasOwn(catalogue.harnesses, harnessId)) {
+    const catHarness = catalogue.harnesses[harnessId];
+    const derived = catHarness.derivedBilling || deriveBilling(catHarness.detectedMode);
+    if (derived === 'free' || derived === 'metered') {
+      if (base === 'metered') {
+        return { value: 'metered', source: 'registry' };
+      }
+      return {
+        value: derived,
+        source: 'derived',
+        detectedMode: catHarness.detectedMode,
+      };
+    }
+  }
+
+  // 3. Fallback to registry descriptor
+  return { value: base, source: 'registry' };
+}
+
+module.exports = { readWorkerBilling, deriveBilling, effectiveBilling };

package/src/runtime/settings/write.js

@@ -0,0 +1,269 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/** Atomic writer for one user or project settings layer (086 IC-011). */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { randomBytes } = require('node:crypto');
+const { isDeepStrictEqual } = require('node:util');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { loadSettingsRegistry } = require('./registry.js');
+const { MAX_BYTES, readLayerFile, validateValue } = require('./files.js');
+const { clearSettingsCache } = require('./resolve.js');
+const { containedDoflow } = require('./project-layers.js');
+
+function isObject(value         )                                   {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function invalid(file        , detail        , code                = null) {
+  return { ok: false         , reason: 'config-invalid'         , code, detail: `${file}: ${detail}` };
+}
+
+function scrub(value     , keys             )      {
+  if (Array.isArray(value)) return value.map((entry) => scrub(entry, keys));
+  if (!isObject(value)) return value;
+  const out                          = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (!keys.has(key)) Object.defineProperty(out, key, { value: scrub(entry, keys), enumerable: true, configurable: true, writable: true });
+  }
+  return out;
+}
+
+/** A layer document as written: `schema` first, then the owned keys in registry order, then the rest. */
+function layerDocument(registry     , values                         )                          {
+  const after                          = { schema: 1 };
+  for (const key of registry.keys.keys()) {
+    if (Object.hasOwn(values, key)) after[key] = values[key];
+  }
+  for (const [key, value] of Object.entries(values)) {
+    if (key !== 'schema' && !registry.keys.has(key)) {
+      Object.defineProperty(after, key, { value, enumerable: true, configurable: true, writable: true });
+    }
+  }
+  return after;
+}
+
+/** The bytes of a layer file. The one serializer: a check that measures a write measures these. */
+function serializeLayer(document                         )         {
+  return Buffer.from(`${JSON.stringify(document, null, 2)}\n`, 'utf8');
+}
+
+/** The refusal for bytes the layer reader (`readLayerFile`, MAX_BYTES) would reject as too-large. */
+function oversize(file        , bytes        )      {
+  if (bytes.length <= MAX_BYTES) return null;
+  return invalid(file, `would be ${bytes.length} bytes as written, over the ${MAX_BYTES}-byte limit of a settings file`, 'too-large');
+}
+
+function backupLayerFile(file        , fsImpl = fs)      {
+  let contents;
+  try {
+    contents = fsImpl.readFileSync(file);
+  } catch (error     ) {
+    return invalid(file, `could not be preserved: ${error?.message || 'could not be read'}`);
+  }
+
+  for (let index = 0; ; index++) {
+    const backup = `${file}.bak${index === 0 ? '' : `.${index}`}`;
+    try {
+      fsImpl.writeFileSync(backup, contents, { flag: 'wx', mode: 0o600 });
+      fsImpl.chmodSync(backup, 0o600);
+      return { ok: true, file: backup };
+    } catch (error     ) {
+      if (error?.code === 'EEXIST') continue;
+      try { fsImpl.rmSync(backup, { force: true }); } catch { /* preserve the primary refusal */ }
+      return invalid(file, `could not be preserved: ${error?.message || 'could not be written'}`);
+    }
+  }
+}
+
+/**
+ * Keep the bytes a write replaces in `<file>.config.bak`, replaced atomically on every write, so the
+ * backup stays one file however often a layer is written. It is not backupLayerFile's `.bak[.N]`
+ * series, which preserves a malformed file once and must never be overwritten by a later write.
+ */
+function replaceBackup(file        , fsImpl     )      {
+  const backup = `${file}.config.bak`;
+  const temporary = path.join(path.dirname(file), `.${path.basename(backup)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+  try {
+    fsImpl.writeFileSync(temporary, fsImpl.readFileSync(file), { flag: 'wx', mode: 0o600 });
+    fsImpl.chmodSync(temporary, 0o600);
+    fsImpl.renameSync(temporary, backup);
+    return { ok: true, file: backup };
+  } catch (error     ) {
+    try { fsImpl.rmSync(temporary, { force: true }); } catch { /* preserve the primary refusal */ }
+    return invalid(file, `could not be backed up: ${error?.message || 'could not be written'}`);
+  }
+}
+
+/** How long a writer waits for another writer's lock. */
+const LOCK_WAIT_MS = 2000;
+const PAUSE = new Int32Array(new SharedArrayBuffer(4));
+
+/**
+ * Take `<file>.lock` (created exclusively, holding a token) so one read-merge-rename of a layer runs at a
+ * time across processes. A held lock is waited on for LOCK_WAIT_MS, then refused with code `locked`, naming
+ * the lock and its age. A lock is never removed automatically, whatever its age: a writer stalled in its
+ * critical section would otherwise lose its write silently, and a lock left by a crashed writer is one
+ * file the person removes.
+ */
+function acquireLock(file        , fsImpl     )      {
+  const lock = `${file}.lock`;
+  const token = `${process.pid} ${randomBytes(8).toString('hex')}\n`;
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      fsImpl.writeFileSync(lock, token, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+      return { ok: true, lock, token };
+    } catch (error     ) {
+      if (error?.code !== 'EEXIST') return invalid(file, `could not be locked: ${error?.message || 'lock not created'}`, 'locked');
+    }
+    let age        ;
+    try { age = Math.round((Date.now() - fsImpl.statSync(lock).mtimeMs) / 1000); } catch (error     ) {
+      if (error?.code === 'ENOENT') continue;
+      age = NaN;
+    }
+    if (Date.now() >= deadline) {
+      const aged = Number.isFinite(age) ? `${Math.max(age, 0)} s old` : 'age unknown';
+      return invalid(file, `is held by the lock ${lock} (${aged}); nothing was written; if no writer is running, remove that lock file and run it again`, 'locked');
+    }
+    Atomics.wait(PAUSE, 0, 0, 20);
+  }
+}
+
+function releaseLock({ lock, token }     , fsImpl     )       {
+  try {
+    if (fsImpl.readFileSync(lock, 'utf8') === token) fsImpl.rmSync(lock, { force: true });
+  } catch { /* already gone; keep the primary result */ }
+}
+
+/**
+ * Write one layer. The read, merge and rename run under the layer's lock (`acquireLock`), so two
+ * writers of different keys never drop each other's key. `expect` (optional): the document the caller
+ * validated against, or null when it found no file; when the file under the lock differs, nothing is
+ * written and the result has code `changed`, so a caller's verdict always describes what it replaces.
+ * `backup` (optional): before an existing file is replaced, keep its bytes (`replaceBackup`).
+ */
+function writeLayer({ file, set = {}, unset = [], scrubKeys = [], force = false, expect, backup = false, fsImpl = fs }      = {})      {
+  if (typeof file !== 'string' || file.length === 0) {
+    return { ok: false, reason: 'config-invalid', detail: 'file is required' };
+  }
+  if (!isObject(set) || !Array.isArray(unset) || unset.some((key) => typeof key !== 'string')) {
+    return invalid(file, 'set must be an object and unset must be an array of keys');
+  }
+
+  if (!Array.isArray(scrubKeys) || scrubKeys.some((key     ) => typeof key !== 'string')) {
+    return invalid(file, 'scrubKeys must be an array of keys');
+  }
+  const loaded = loadSettingsRegistry({ repoRoot: REPO_ROOT, fsImpl });
+  if (!loaded.ok) return invalid(file, `settings registry is invalid: ${loaded.detail}`);
+  const { registry } = loaded;
+  const unsetKeys = new Set(unset);
+  for (const [key, value] of Object.entries(set)) {
+    const spec = registry.keys.get(key);
+    if (!spec) return invalid(file, `unknown owned key '${key}'`);
+    if (unsetKeys.has(key)) return invalid(file, `key '${key}' cannot be both set and unset`);
+    const fault = validateValue(spec, value, registry.enumValues(key));
+    if (fault) return invalid(file, `'${key}' ${fault.reason}`);
+  }
+  for (const key of unsetKeys) {
+    if (!registry.keys.has(key)) return invalid(file, `unknown owned key '${key}'`);
+  }
+  for (const key of scrubKeys) {
+    if (!registry.keys.has(key) || !Object.hasOwn(set, key)) return invalid(file, `scrub key '${key}' must be a registered key also present in set`);
+  }
+
+  try {
+    fsImpl.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  } catch (error     ) {
+    return invalid(file, error?.message || 'could not be written');
+  }
+  const held = acquireLock(file, fsImpl);
+  if (!held.ok) return held;
+  try {
+    return replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect, backup, fsImpl });
+  } finally {
+    releaseLock(held, fsImpl);
+  }
+}
+
+const INVALID = Symbol('invalid layer');
+
+/** The read, merge and rename of `writeLayer`, run while it holds the layer's lock. */
+function replaceLayer({ file, registry, set, unsetKeys, scrubKeys, force, expect, backup, fsImpl }     )      {
+  let before                                 = null;
+  let existing                          = {};
+  let layer     ;
+  try {
+    layer = readLayerFile(file, { registry, fsImpl, includeDocument: true });
+    if (layer.status === 'invalid') {
+      if (!force) return invalid(file, `${layer.code}: ${layer.reason}`, layer.code);
+    } else if (layer.status === 'ok') {
+      if (!isObject(layer.document)) {
+        if (!force) return invalid(file, 'must be a JSON object', 'unparseable');
+      } else {
+        before = layer.document;
+        existing = scrub(layer.document, new Set(scrubKeys));
+      }
+    }
+  } catch (error     ) {
+    if (!force) return invalid(file, 'could not be read');
+    before = null;
+    existing = {};
+  }
+
+  if (expect !== undefined) {
+    const current = layer?.status === 'ok' ? layer.document : layer?.status === 'absent' ? null : INVALID;
+    if (!isDeepStrictEqual(current, expect)) {
+      return invalid(file, 'changed while this write was being checked; nothing was written', 'changed');
+    }
+  }
+
+  const changed = layer?.status !== 'ok'
+    || scrubKeys.length > 0
+    || Object.entries(set).some(([key, value]) => !Object.hasOwn(existing, key) || existing[key] !== value)
+    || [...unsetKeys].some((key) => Object.hasOwn(existing, key));
+  if (!changed) return { ok: true, file, before, after: existing };
+
+  const values                          = { ...existing };
+  for (const [key, value] of Object.entries(set)) values[key] = value;
+  for (const key of unsetKeys) delete values[key];
+
+  const after = layerDocument(registry, values);
+  const bytes = serializeLayer(after);
+  const tooLarge = oversize(file, bytes);
+  if (tooLarge) return tooLarge;
+
+  if (backup && layer?.status !== 'absent') {
+    const kept = replaceBackup(file, fsImpl);
+    if (!kept.ok) return kept;
+  }
+
+  const directory = path.dirname(file);
+  let temporary                = null;
+  try {
+    temporary = path.join(directory, `.${path.basename(file)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    fsImpl.writeFileSync(temporary, bytes, { flag: 'wx', mode: 0o600 });
+    fsImpl.chmodSync(temporary, 0o600);
+    if (path.basename(directory) === '.doflow') {
+      const root = path.dirname(directory);
+      if (!containedDoflow(root, fsImpl)) {
+        return invalid(file, '.doflow symlink points outside the project', 'scope');
+      }
+    }
+    fsImpl.renameSync(temporary, file);
+    temporary = null;
+    clearSettingsCache();
+    return { ok: true, file, before, after };
+  } catch (error     ) {
+    return invalid(file, error?.message || 'could not be written');
+  } finally {
+    if (temporary !== null) {
+      try { fsImpl.rmSync(temporary, { force: true }); } catch { /* keep the primary result */ }
+    }
+  }
+}
+
+module.exports = { writeLayer, backupLayerFile, layerDocument, serializeLayer, oversize };

package/src/runtime/slot-command.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * The `slot` verb's argument checks and output forms (feature 115, IC-008). The queue itself is
+ * `./slots.js`; this file only maps flags to it and its results to exit codes.
+ */
+
+const { runSlot, listSlots, peekSlots, releaseSlot } = require('./slots.js');
+const { finishRuntime } = require('./cli-result.js');
+
+const TIMEOUT_MAX = 86400;
+
+function refuse(message        , json         )         {
+  if (json) console.log(JSON.stringify({ ok: false, error: 'usage', message }));
+  else console.error(`doflow slot: ${message}`);
+  return finishRuntime(2);
+}
+
+async function handleSlotCommand({
+  action, name, label, timeout, noWait = false, command, by, reason, positional = [], extraFlags = [], json = false, env = process.env, cwd = process.cwd(),
+}      = {})                  {
+  const usage = 'usage: slot --action run|list|peek|release (see doflow --help)';
+  if (extraFlags.length > 0) return refuse(`unknown flag '${extraFlags[0]}'; ${usage}`, json);
+  if (positional.length > 0) return refuse(`unexpected argument '${positional[0]}'; ${usage}`, json);
+  if (action !== 'run' && action !== 'list' && action !== 'peek' && action !== 'release') return refuse(`--action must be run, list, peek or release; ${usage}`, json);
+  try {
+    if (action === 'run') {
+      if (!Array.isArray(command)) return refuse('slot run needs the command after --, as in: slot --action run --name <name> -- <command> [args...]', json);
+      let timeoutSeconds                    ;
+      if (timeout !== undefined) {
+        if (!Number.isInteger(timeout) || timeout < 1 || timeout > TIMEOUT_MAX) return refuse(`--timeout must be a whole number of seconds from 1 to ${TIMEOUT_MAX}`, json);
+        timeoutSeconds = timeout;
+      }
+      return finishRuntime(await runSlot({ name, command, label, timeoutSeconds, noWait, cwd, env }));
+    }
+    if (action === 'list') {
+      const listed = await listSlots({ env, json });
+      console.log(listed.output);
+      return finishRuntime(0);
+    }
+    if (action === 'peek') {
+      // 093 IC-018 b: a read with no lock, sweep or mkdir; no pid, start or cwd in either form.
+      const peeked = await peekSlots({ env, cwd });
+      if (json) console.log(JSON.stringify(peeked));
+      else if (peeked.slots.length === 0) console.log('no slots held');
+      else {
+        for (const slot of peeked.slots) {
+          const head = slot.holder
+            ? `held (${slot.holder.label}) since ${slot.holder.since}, alive ${slot.holder.alive}${slot.holder.worktreeKey ? `, checkout ${slot.holder.worktreeKey}` : ', another directory'}`
+            : 'free';
+          console.log(`${slot.name}  ${head}; ${slot.waiters} waiting`);
+        }
+      }
+      if (!json && peeked.unreadable > 0) console.log(`unreadable: ${peeked.unreadable}`);
+      return finishRuntime(0);
+    }
+    const released = await releaseSlot({ name, by, reason, env });
+    if (json) console.log(JSON.stringify(released));
+    else {
+      const held = released.holder ? ` (holder ${released.holder.pid}, ${released.holder.label})` : '';
+      const line = `slot ${name}: ${released.disposition}${held}`;
+      if (released.ok) console.log(line); else console.error(line);
+    }
+    return finishRuntime(released.ok ? 0 : 1);
+  } catch (error     ) {
+    if (error.code === 'usage') return refuse(error.message, json);
+    if (error.code === 'no-home' || error.code === 'slots-unsafe') {
+      if (json) console.log(JSON.stringify({ ok: false, error: error.code, message: error.message }));
+      else console.error(`doflow slot: ${error.message}`);
+      return finishRuntime(1);
+    }
+    throw error;
+  }
+}
+
+module.exports = { handleSlotCommand };