@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.4

package/src/release/build-package.js

@@ -0,0 +1,91 @@
+'use strict';
+
+// Build the JavaScript form published to npm in an isolated staging directory. The checkout stays
+// TypeScript so local development and the source CLI keep using Node's native type stripping.
+const fs = require('node:fs');
+const path = require('node:path');
+const { stripTypeScriptTypes } = require('node:module');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+const TEXT_EXTENSIONS = new Set(['.js', '.json', '.sh', '.md', '.yaml', '.yml']);
+
+function walkFiles(root        )           {
+  const files           = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const file = path.join(root, entry.name);
+    if (entry.isDirectory()) files.push(...walkFiles(file));
+    else if (entry.isFile()) files.push(file);
+  }
+  return files;
+}
+
+function buildPackage(outDir        , { repoRoot = REPO_ROOT }                        = {})         {
+  if (typeof stripTypeScriptTypes !== 'function') {
+    throw new Error('Node does not provide node:module.stripTypeScriptTypes');
+  }
+  const packageJson = JSON.parse(fs.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  const output = path.resolve(outDir);
+  fs.rmSync(output, { recursive: true, force: true });
+  fs.mkdirSync(output, { recursive: true });
+
+  for (const rel of packageJson.files || []) {
+    const source = path.join(repoRoot, rel);
+    if (fs.existsSync(source)) fs.cpSync(source, path.join(output, rel), { recursive: true });
+  }
+  for (const name of ['package.json', 'README.md', 'LICENSE', 'CHANGELOG.md']) {
+    const source = path.join(repoRoot, name);
+    if (fs.existsSync(source)) fs.copyFileSync(source, path.join(output, name));
+  }
+
+  const converted = new Set        ();
+  for (const file of walkFiles(path.join(output, 'src'))) {
+    if (!file.endsWith('.ts') || file.endsWith('.d.ts')) continue;
+    const relative = path.relative(output, file).split(path.sep).join('/');
+    const jsRelative = relative.slice(0, -3) + '.js';
+    const code = fs.readFileSync(file, 'utf8');
+    fs.writeFileSync(path.join(output, jsRelative), stripTypeScriptTypes(code, { mode: 'strip' }));
+    fs.rmSync(file);
+    converted.add(relative);
+  }
+
+  for (const file of walkFiles(output)) {
+    if (!TEXT_EXTENSIONS.has(path.extname(file))) continue;
+    const relative = path.relative(output, file).split(path.sep).join('/');
+    let content = fs.readFileSync(file, 'utf8');
+    content = content.replace(/(['"`])((?:\.\.?\/)[^'"`\n]*?\.ts)\1/g, (whole        , quote        , specifier        ) => {
+      const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(relative), specifier));
+      if (!converted.has(resolved)) return whole;
+      return `${quote}${specifier.slice(0, -3)}.js${quote}`;
+    });
+    for (const rel of [...converted].sort((a, b) => b.length - a.length)) {
+      content = content.split(rel).join(rel.slice(0, -3) + '.js');
+    }
+    fs.writeFileSync(file, content);
+  }
+
+  const remaining = walkFiles(output);
+  const runtimeFiles = ['src', 'bin'].flatMap((directory) => {
+    const root = path.join(output, directory);
+    return fs.existsSync(root) ? walkFiles(root) : [];
+  });
+  const nonDeclarationTs = runtimeFiles.filter((file        ) => file.endsWith('.ts') && !file.endsWith('.d.ts'));
+  if (nonDeclarationTs.length) throw new Error(`staged package retains TypeScript files: ${nonDeclarationTs.join(', ')}`);
+  for (const file of remaining) {
+    if (!TEXT_EXTENSIONS.has(path.extname(file))) continue;
+    const content = fs.readFileSync(file, 'utf8');
+    const unresolved = [...converted].filter((rel) => content.includes(rel));
+    if (unresolved.length) throw new Error(`${path.relative(output, file)} still references converted TypeScript paths: ${unresolved.join(', ')}`);
+  }
+  return output;
+}
+
+if (require.main === module) {
+  const outDir = process.argv[2];
+  if (!outDir) {
+    process.stderr.write('Usage: node src/release/build-package.js <outDir>\n');
+    process.exit(2);
+  }
+  buildPackage(outDir);
+}
+
+module.exports = { buildPackage };

package/src/release/changelog-section.js

@@ -0,0 +1,70 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// ── One release version, one CHANGELOG section, one GitHub Release body ─────────────────────────
+//
+// `gh release create --generate-notes` lists merged pull requests, and this repository merges
+// locally, so every Release the workflow created carried only a compare link. CHANGELOG.md is
+// where the release text is already written (Keep a Changelog, one `## [X.Y.Z]` heading per
+// version), so the release workflow extracts the tagged version's section from it and passes that
+// as the Release body. A tag whose section is missing or empty fails the job instead of
+// publishing an empty Release.
+//
+// Usage: node src/release/changelog-section.js <version|tag> [CHANGELOG path]
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+function escapeRegExp(text        )         {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Returns the body of a version's section: the lines after its `## [version]` heading up to the
+ * next `## [` heading, trimmed. The closing `]` after the version makes 1.2.1 and 1.2.10 distinct.
+ * A leading `v` on the version is ignored. Returns null when the heading is absent or the body is
+ * empty.
+ * @param {string} changelogText
+ * @param {string} version
+ * @returns {string|null}
+ */
+function changelogSection(changelogText        , version        )                {
+  const wanted = String(version).trim().replace(/^v/, '');
+  if (wanted === '') return null;
+  const lines = changelogText.split(/\r?\n/);
+  const heading = new RegExp(`^##\\s+\\[${escapeRegExp(wanted)}\\](\\s|$)`);
+  const start = lines.findIndex((line) => heading.test(line));
+  if (start === -1) return null;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^##\s+\[/.test(lines[i])) { end = i; break; }
+  }
+  const body = lines.slice(start + 1, end).join('\n').trim();
+  return body === '' ? null : body;
+}
+
+if (require.main === module) {
+  const version = process.argv[2];
+  const file = process.argv[3] || path.join(REPO_ROOT, 'CHANGELOG.md');
+  if (!version) {
+    console.error('usage: node src/release/changelog-section.js <version|tag> [CHANGELOG path]');
+    process.exit(1);
+  }
+  let text        ;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    console.error(`cannot read ${file}: ${(err         ).message}`);
+    process.exit(1);
+  }
+  const body = changelogSection(text, version);
+  if (body === null) {
+    console.error(`no non-empty CHANGELOG section for ${String(version).replace(/^v/, '')} in ${file}`);
+    process.exit(1);
+  }
+  process.stdout.write(`${body}\n`);
+}
+
+module.exports = { changelogSection };

package/src/release/sync-plugin-versions.js

@@ -0,0 +1,66 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+// ── One release version, projected into every distribution manifest ─────────────────────────────
+//
+// package.json is the single source of the release version. The three plugin manifests (Codex,
+// Claude, Copilot) each repeat it, and v1.2.1 shipped with all three still reading 1.2.0 — the
+// guard tests comparing them were failing correctly (architecture review R8). Hand-editing four
+// files in step is exactly the drift class this repo removes elsewhere by generation, so the
+// npm `version` lifecycle hook runs this script: `npm version <bump>` rewrites the manifests and
+// stages them into the same release commit. The equality guards in test/install/doflow.test.js
+// stay as the independent check that the projection actually happened.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { REPO_ROOT } = require('../helper/repo-root.js');
+
+/** Every distribution manifest that repeats the release version, relative to the repo root. */
+const PLUGIN_MANIFESTS = [
+  'core/.codex-plugin/plugin.json',
+  'core/.claude-plugin/plugin.json',
+  'core/.plugin/plugin.json',
+];
+
+/**
+ * Rewrites each plugin manifest's version to package.json's, preserving formatting by targeted
+ * string replacement rather than re-serializing the whole file.
+ * @param {Object} [options]
+ * @param {string} [options.repoRoot]
+ * @param {Object} [options.fsImpl]
+ * @returns {{version: string, updated: Array<string>, unchanged: Array<string>}}
+ */
+function syncPluginVersions({ repoRoot = REPO_ROOT, fsImpl = fs }                                      = {})                                                              {
+  const pkg = JSON.parse(fsImpl.readFileSync(path.join(repoRoot, 'package.json'), 'utf8'));
+  if (typeof pkg.version !== 'string' || pkg.version.trim() === '') {
+    throw new Error('package.json declares no version to project');
+  }
+
+  const updated           = [];
+  const unchanged           = [];
+  for (const rel of PLUGIN_MANIFESTS) {
+    const file = path.join(repoRoot, rel);
+    const text = fsImpl.readFileSync(file, 'utf8');
+    const manifest = JSON.parse(text);
+    if (manifest.version === pkg.version) {
+      unchanged.push(rel);
+      continue;
+    }
+    const next = text.replace(/"version":\s*"[^"]*"/, `"version": "${pkg.version}"`);
+    if (!/"version":\s*"/.test(text)) {
+      throw new Error(`${rel} has no version field to rewrite — the manifest shape changed; update PLUGIN_MANIFESTS`);
+    }
+    fsImpl.writeFileSync(file, next, 'utf8');
+    updated.push(rel);
+  }
+  return { version: pkg.version, updated, unchanged };
+}
+
+if (require.main === module) {
+  const result = syncPluginVersions();
+  for (const rel of result.updated) console.log(`synced ${rel} -> ${result.version}`);
+  if (result.updated.length === 0) console.log(`all plugin manifests already at ${result.version}`);
+}
+
+module.exports = { syncPluginVersions, PLUGIN_MANIFESTS };

package/src/runtime/advice/cli.js

@@ -0,0 +1,283 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { finishRuntime, usageError } = require('../cli-result.js');
+const { REPO_ROOT } = require('../../helper/repo-root.js');
+const { loadAdviceRegistry } = require('./registry.js');
+const { loadStorageRegistry } = require('../storage/registry.js');
+const { resolveRoots } = require('../storage/roots.js');
+const { resolveSetting, writeSetting } = require('./config.js');
+const { createAdviceClient } = require('./client.js');
+const { materializeKind, validateQuestionSet, validateStaticAnswer } = require('./kinds.js');
+const { findPick, appendOutcome } = require('./record.js');
+const { strengthWords } = require('./strength.js');
+
+function loadSources(repoRoot     ) {
+  const read = (name     ) => JSON.parse(fs.readFileSync(path.join(repoRoot, 'core/registry', name), 'utf8'));
+  return {
+    workflows: read('workflows.json'),
+    verification: read('verification.json'),
+    mcp: read('mcp.json'),
+  };
+}
+
+function loadRuntime({ projectRoot, global = false }      = {}) {
+  const advice = loadAdviceRegistry({ repoRoot: REPO_ROOT });
+  const storage = loadStorageRegistry({ repoRoot: REPO_ROOT });
+  const roots = resolveRoots({ registry: storage, projectRoot, global });
+  const sources = loadSources(REPO_ROOT);
+  const adviceRegistry = advice.ok ? advice.registry : null;
+  return { adviceRegistry, adviceError: advice.ok ? null : advice.detail, storage, roots, sources };
+}
+
+function emitResult(result     , { json, kind }     ) {
+  if (result.reason === 'over-limit') {
+    return usageError('advise', result.detail || 'request exceeds an advice limit', json);
+  }
+  if (json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (result.status === 'answered') {
+    for (const answer of result.answers) {
+      const staticText = answer.staticAnswer === null ? '' : ` Static answer: ${answer.staticAnswer}.`;
+      console.log(`Advice (${kind}): ${answer.pick}, ${strengthWords(answer.strength)}.${staticText}`);
+    }
+  } else {
+    console.log(`Advice (${kind}): none; the static answer stands.`);
+  }
+  return finishRuntime(0);
+}
+
+function isPresent(value     ) {
+  return value !== undefined && value !== null;
+}
+
+function readState({ state, stateFile, json }     ) {
+  if (isPresent(state) === isPresent(stateFile)) {
+    usageError('advise', 'provide exactly one of --state or --state-file', json);
+    return null;
+  }
+  if (isPresent(state)) return state;
+  try {
+    const content = fs.readFileSync(stateFile, 'utf8');
+    if (!content.length) throw new Error('file is empty');
+    return content;
+  } catch (error     ) {
+    usageError('advise', `cannot read state file ${stateFile}: ${error.message}`, json);
+    return null;
+  }
+}
+
+function readQuestions(file     , json     ) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed) || !Array.isArray(parsed.questions)) {
+      throw new Error('expected an object with a questions array');
+    }
+    return parsed.questions;
+  } catch (error     ) {
+    usageError('advise', `cannot read questions file ${file}: ${error.message}`, json);
+    return null;
+  }
+}
+
+function parseAskInput(options     ) {
+  const hasKind = typeof options.kind === 'string' && options.kind.length > 0;
+  const hasQuestionsFile = isPresent(options.questionsFile);
+  if (hasKind === hasQuestionsFile) {
+    usageError('advise', 'provide exactly one of --kind or --questions-file', options.json);
+    return null;
+  }
+  const state = readState({ state: options.state, stateFile: options.stateFile, json: options.json });
+  if (state === null) return null;
+  if (options.server !== undefined && !hasKind) {
+    usageError('advise', '--server is only valid with --kind mcp-need', options.json);
+    return null;
+  }
+  if (options.staticAnswer !== undefined && !hasKind) {
+    usageError('advise', '--static is only valid with a named --kind', options.json);
+    return null;
+  }
+  return { state, hasKind, hasQuestionsFile };
+}
+
+function endpointSource(userSetting     , endpoint     ) {
+  if (userSetting?.decidedBy?.user) {
+    try {
+      const file = JSON.parse(fs.readFileSync(userSetting.decidedBy.user, 'utf8'));
+      if (file.endpoint === endpoint) return userSetting.decidedBy.user;
+    } catch { /* an invalid file will be reported by its resolver/writer */ }
+  }
+  return 'provider default';
+}
+
+function inspectFailure(inspected     , { endpoint, model, provider }     ) {
+  if (inspected.endpoint.state === 'refused') return inspected.endpoint.message;
+  if (inspected.endpoint.state !== 'reached') {
+    return `advise: Ollama did not answer at ${endpoint}; start it yourself and re-run. Nothing was written.`;
+  }
+  if (!inspected.endpoint.versionOk) {
+    return `advise: Ollama ${inspected.endpoint.version || 'unknown'} at ${endpoint} is older than ${provider.minVersion}. Nothing was written.`;
+  }
+  if (!inspected.model.installed) {
+    return `advise: model ${model} is not installed; run 'ollama pull ${model}' yourself. Nothing was written.`;
+  }
+  if (!inspected.model.decisionCapable) {
+    const capable = inspected.models
+      .filter((entry     ) => Array.isArray(entry.capabilities) && entry.capabilities.includes(provider.capability))
+      .map((entry     ) => entry.name);
+    return `advise: model ${model} is not decision-capable; decision-capable here: ${capable.length ? capable.join(', ') : 'none'}. Nothing was written.`;
+  }
+  return null;
+}
+
+function writeFailure(message     , json     ) {
+  if (json) console.log(JSON.stringify({ ok: false, error: 'write-failed', message }, null, 2));
+  else if (message.startsWith('decision model: endpoint ') || message.startsWith('advise:')) console.error(message);
+  else console.error(`advise: ${message}`);
+  return finishRuntime(1);
+}
+
+async function handleConfigure(options     , runtime     ) {
+  const { adviceRegistry, adviceError, roots, sources } = runtime;
+  const { json, project, global, force } = options;
+  const hasModel = typeof options.model === 'string' && options.model.length > 0;
+  const hasOff = options.off === true;
+  if (hasModel && hasOff) return usageError('advise', 'cannot combine --model and --off', json);
+  if (!hasModel && !hasOff) return usageError('advise', 'provide exactly one of --model or --off', json);
+  if (project && options.endpoint !== undefined) return usageError('advise', '--endpoint cannot be used with --project', json);
+  if (hasOff && options.endpoint !== undefined) return usageError('advise', '--endpoint cannot be used with --off', json);
+  if (project && (global || !options.projectRoot)) return usageError('advise', '--project requires a project root', json);
+  if (adviceError || !adviceRegistry) return writeFailure(`advice registry is invalid: ${adviceError || 'missing registry'}`, json);
+
+  const file = project
+    ? path.join(roots['project-doflow'], 'decision-model.json')
+    : path.join(roots['config-home'], 'decision-model.json');
+  const fsImpl = fs;
+  if (hasOff) {
+    const setting = project ? { schema: 1, enabled: false } : { schema: 1, enabled: false };
+    const written = writeSetting({ file, level: project ? 'project' : 'user', setting, force, fsImpl });
+    if (!written.ok) return writeFailure(written.detail, json);
+    const effective = resolveSetting({ adviceRegistry, roots, fsImpl });
+    if (json) console.log(JSON.stringify({ written: file, setting: effective }, null, 2));
+    else console.log(project ? `Decision model for this project: off (wrote ${file}).` : `Decision model off (wrote ${file}).`);
+    return finishRuntime(0);
+  }
+
+  let userRoots = roots;
+  if (project) userRoots = { ...roots, 'project-doflow': null };
+  const userSetting = resolveSetting({ adviceRegistry, roots: userRoots, fsImpl });
+  if (project && userSetting.state !== 'on') {
+    return writeFailure('turn the decision model on at user level first; a project cannot enable it', json);
+  }
+  const providerId = userSetting.provider || 'ollama';
+  const provider = adviceRegistry.providers.find((entry     ) => entry.id === providerId);
+  if (!provider) return writeFailure(`provider '${providerId}' is not in core/registry/advice.json`, json);
+  const endpoint = project
+    ? userSetting.endpoint
+    : options.endpoint || userSetting.endpoint || provider.defaultEndpoint;
+  const endpointFile = options.endpoint ? '--endpoint' : endpointSource(userSetting, endpoint);
+  const client = createAdviceClient({ adviceRegistry, roots, sources });
+  const inspected = await client.inspect({ endpoint, model: options.model, provider: provider.id, minVersion: provider.minVersion, file: endpointFile });
+  const failure = inspectFailure(inspected, { endpoint, model: options.model, provider });
+  if (failure) return writeFailure(failure, json);
+
+  const setting = project
+    ? { schema: 1, model: options.model }
+    : { schema: 1, enabled: true, provider: provider.id, endpoint, model: options.model };
+  const written = writeSetting({ file, level: project ? 'project' : 'user', setting, force, fsImpl });
+  if (!written.ok) return writeFailure(written.detail, json);
+  const effective = resolveSetting({ adviceRegistry, roots, fsImpl });
+  if (json) console.log(JSON.stringify({ written: file, setting: effective }, null, 2));
+  else console.log(project
+    ? `Decision model for this project: ${options.model} (wrote ${file}).`
+    : `Decision model on: ${options.model} at ${endpoint} (wrote ${file}).`);
+  return finishRuntime(0);
+}
+
+async function handleAsk(options     , runtime     ) {
+  const parsed = parseAskInput(options);
+  if (!parsed) return finishRuntime(2);
+  const { adviceRegistry, adviceError, roots, sources } = runtime;
+  if (adviceError || !adviceRegistry) {
+    const result = {
+      status: 'off', reason: 'config-invalid', detail: adviceError || 'advice registry is missing',
+      provider: null, model: null, endpoint: null, decidedBy: { user: null, project: null }, durationMs: 0, answers: [],
+    };
+    return emitResult(result, { json: options.json, kind: options.kind || 'adhoc' });
+  }
+
+  let kind = 'adhoc';
+  let questionSet;
+  let questionError = null;
+  if (parsed.hasKind) {
+    kind = options.kind;
+    const built = materializeKind(kind, { adviceRegistry, sources, server: options.server });
+    if (!built.ok && built.reason === 'usage-error') return usageError('advise', built.detail, options.json);
+    if (built.ok) questionSet = { state: parsed.state, questions: [built.question] };
+    else {
+      questionSet = { state: parsed.state, questions: [] };
+      questionError = built.detail;
+    }
+    if (options.staticAnswer !== undefined && built.ok) {
+      const validation = validateStaticAnswer(built.question, options.staticAnswer);
+      if (!validation.ok) return usageError('advise', validation.detail, options.json);
+    }
+  } else {
+    const questions = readQuestions(options.questionsFile, options.json);
+    if (!questions) return finishRuntime(2);
+    questionSet = { state: parsed.state, questions };
+    const validation = validateQuestionSet(questionSet, { adviceRegistry });
+    if (!validation.ok) return usageError('advise', validation.detail, options.json);
+  }
+
+  const client = createAdviceClient({ adviceRegistry, roots, sources });
+  const result = await client.ask({
+    questionSet, kind, staticAnswer: options.staticAnswer, caller: 'advise', taskId: options.taskId,
+    record: true,
+  });
+  // Preserve the kind materialiser's source-specific diagnostic while the client owns miss recording.
+  if (questionError && result.reason === 'config-invalid') result.detail = questionError;
+  return emitResult(result, { json: options.json, kind });
+}
+
+function handleOutcome(options     , runtime     ) {
+  const { json } = options;
+  if (typeof options.pickId !== 'string' || !options.pickId) return usageError('advise', '--pick-id is required', json);
+  if (typeof options.actual !== 'string' || !options.actual) return usageError('advise', '--actual is required', json);
+  const found = findPick({ pickId: options.pickId, roots: runtime.roots });
+  if (!found) {
+    if (json) console.log(JSON.stringify({ ok: false, error: 'not-found', message: `no pick ${options.pickId} in the retained record` }, null, 2));
+    else console.error(`advise: no pick ${options.pickId} in the retained record`);
+    return finishRuntime(1);
+  }
+  if (!found.pick.options?.includes(options.actual)) {
+    return usageError('advise', `--actual must be one of: ${found.pick.options.join(', ')}`, json);
+  }
+  const written = appendOutcome({
+    pickId: options.pickId, actual: options.actual, source: 'caller', roots: runtime.roots, store: found.store,
+  });
+  if (!written) return writeFailure(`could not record outcome for ${options.pickId}`, json);
+  if (json) console.log(JSON.stringify({ pickId: options.pickId, actual: options.actual, recorded: true, file: written.file }, null, 2));
+  else console.log(`Recorded outcome ${options.actual} for ${options.pickId}.`);
+  return finishRuntime(0);
+}
+
+async function handleAdviseCommand(options      = {}) {
+  const action = options.actionGiven ? options.action : 'ask';
+  if (!['ask', 'outcome', 'configure'].includes(action)) return usageError('advise', `unknown action '${action}'`, options.json);
+  try {
+    const projectRoot = options.global ? null : path.resolve(options.projectRoot || process.cwd());
+    const runtime = loadRuntime({ projectRoot, global: options.global });
+    const shaped = { ...options, projectRoot };
+    if (action === 'configure') return await handleConfigure(shaped, runtime);
+    if (action === 'outcome') return handleOutcome(shaped, runtime);
+    return await handleAsk(shaped, runtime);
+  } catch (error     ) {
+    return writeFailure(error?.message || 'advice command failed', options.json);
+  }
+}
+
+module.exports = { handleAdviseCommand };