@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/outline/vue-outline.js

@@ -0,0 +1,88 @@
+/**
+ * Vue-aware outline lines: compiler macros (defineProps, defineEmits, defineModel,
+ * defineExpose, withDefaults), Options API objects (defineComponent / export
+ * default {}), and Pinia defineStore (options and setup forms).
+ */
+import { lazyTypes as t } from '../babel-lazy.js';
+
+const MACROS = new Set(['defineProps', 'defineEmits', 'defineModel', 'defineExpose', 'defineSlots', 'defineOptions']);
+const OPTION_SECTIONS = ['props', 'emits', 'data', 'computed', 'methods', 'watch', 'setup', 'state', 'getters', 'actions'];
+
+const isCallNamed = (node, names) => t.isCallExpression(node) && t.isIdentifier(node.callee) && names.has(node.callee.name);
+const keyName = (key) => {
+  const isIdentifierKey = t.isIdentifier(key);
+  if (isIdentifierKey) return key.name;
+  const isStringKey = t.isStringLiteral(key);
+  return isStringKey ? key.value : '';
+};
+const objectKeys = (obj) => (t.isObjectExpression(obj) ? obj.properties.map((p) => keyName(p.key)).filter(Boolean) : []);
+const compact = (text) => text.replace(/\s+/g, ' ').trim();
+
+const returnedObject = (fn) => {
+  const isFunction = t.isArrowFunctionExpression(fn) || t.isFunctionExpression(fn) || t.isObjectMethod(fn);
+  if (!isFunction) return null;
+  if (t.isObjectExpression(fn.body)) return fn.body;
+  const isParenthesized = t.isParenthesizedExpression(fn.body) && t.isObjectExpression(fn.body.expression);
+  if (isParenthesized) return fn.body.expression;
+  const body = t.isBlockStatement(fn.body) ? fn.body.body : [];
+  const ret = [...body].reverse().find((stmt) => t.isReturnStatement(stmt));
+  return t.isObjectExpression(ret?.argument) ? ret.argument : null;
+};
+
+const typeMemberNames = (code, typeNode) => {
+  if (!t.isTSTypeLiteral(typeNode)) return compact(code.slice(typeNode.start, typeNode.end));
+  return typeNode.members.map((m) => {
+    const isCallSignature = t.isTSCallSignatureDeclaration(m);
+    const firstParam = isCallSignature ? m.parameters[0]?.typeAnnotation?.typeAnnotation : null;
+    const eventName = firstParam?.literal?.value;
+    if (eventName) return eventName;
+    return compact(code.slice(m.start, m.end)).replace(/;$/, '');
+  }).join(', ');
+};
+
+/** `defineProps { title: string, count?: number }` style line, or null. */
+export const describeVueMacro = (code, node) => {
+  const isWithDefaults = isCallNamed(node, new Set(['withDefaults'])) && isCallNamed(node.arguments[0], MACROS);
+  const call = isWithDefaults ? node.arguments[0] : node;
+  if (!isCallNamed(call, MACROS)) return null;
+  const typeArg = call.typeParameters?.params?.[0];
+  const arg = call.arguments[0];
+  let detail = '';
+  if (typeArg) detail = typeMemberNames(code, typeArg);
+  else if (t.isObjectExpression(arg)) detail = objectKeys(arg).join(', ');
+  else if (t.isArrayExpression(arg)) detail = arg.elements.filter(t.isStringLiteral).map((el) => el.value).join(', ');
+  return `${call.callee.name} { ${detail} }`;
+};
+
+const describeSections = (obj, indent = '  ') => {
+  const lines = [];
+  for (const prop of obj.properties) {
+    const section = keyName(prop.key);
+    const isOptionSection = OPTION_SECTIONS.includes(section);
+    if (!isOptionSection) continue;
+    const value = t.isObjectProperty(prop) ? prop.value : prop;
+    const returned = returnedObject(value);
+    const members = returned ? objectKeys(returned) : objectKeys(value);
+    const isArray = t.isArrayExpression(value);
+    const names = isArray ? value.elements.filter(t.isStringLiteral).map((el) => el.value) : members;
+    const hasNames = names.length > 0;
+    if (hasNames) lines.push(`${indent}${section}: ${names.join(', ')}`);
+  }
+  return lines;
+};
+
+/** One level into `export default {}` / `defineComponent({})`. */
+export const describeComponentOptions = (code, decl) => {
+  const isDefineComponent = isCallNamed(decl, new Set(['defineComponent'])) && t.isObjectExpression(decl.arguments[0]);
+  const obj = isDefineComponent ? decl.arguments[0] : decl;
+  return t.isObjectExpression(obj) ? describeSections(obj) : [];
+};
+
+/** Members of a Pinia store: options form sections, or the setup function's returned keys. */
+export const describeStore = (code, init) => {
+  if (!isCallNamed(init, new Set(['defineStore']))) return null;
+  const definition = init.arguments.find((arg) => t.isObjectExpression(arg) || t.isArrowFunctionExpression(arg) || t.isFunctionExpression(arg));
+  if (t.isObjectExpression(definition)) return describeSections(definition);
+  const returned = returnedObject(definition);
+  return returned ? [`  returns: ${objectKeys(returned).join(', ')}`] : [];
+};

package/cli/patcher-cli.js

@@ -0,0 +1,255 @@
+/**
+ * CLI runners for `chemx patch` and `chemx write`. Both preview with --dry-run (printing the
+ * full unified diff) and refuse rather than guess: a missing --content never becomes '' and an
+ * unknown flag refuses instead of being ignored.
+ */
+import fs from 'node:fs';
+import { ANSI } from './theme.js';
+import { isStdinTty } from './terminal.js';
+import { parseValueFlags, hasFlag, splitList, hasPreviewFlag, findUnknownFlags, unknownFlagsMessage } from './cli-args.js';
+import { patchFile } from './patcher.js';
+import { writeOrAppend } from './write-append.js';
+import { parseSearchReplaceBlocks } from './search-replace-blocks.js';
+
+const PATCH_HELP = [
+  'USAGE',
+  "  chemx patch <file> [options] <<'EOF'",
+  '  <<<<<<< SEARCH',
+  '  exact old text (any number of lines; quotes, $ and backticks are literal)',
+  '  =======',
+  '  new text (empty deletes the SEARCH lines)',
+  '  >>>>>>> REPLACE',
+  '  EOF',
+  '  chemx patch <file> --target="text" --replacement="new" [options]',
+  '',
+  '  Markers sit at column 0 inside the heredoc; repeat the block for more edits. Blocks apply',
+  '  in order and all-or-nothing: one unmatched block fails the call and writes nothing.',
+  '',
+  'OPTIONS',
+  '  --target=<text>          Exact text to replace (literal; never empty)',
+  '  --replacement=<new>      Replacement text (literal; `$` is not special)',
+  '  --target-file=<path>     Read the target from a file',
+  '  --replacement-file=<p>   Read the replacement from a file',
+  '  --multiple               Replace every occurrence',
+  '  --allow-remove=<a,b>     Top-level declarations the patch may remove',
+  '  --allow-missing-import   Allow the edit although it leaves an import unresolved',
+  '  --as=<agent>             Agent id for team lock checks (default $CHEMX_AGENT_ID, else unique to this process)',
+  '  -n, --dry-run            Print the unified diff without writing (--dryRun, --dry-run=<any> too)',
+  '  --json                   Output result as JSON',
+  '  -h, --help               Show this help message',
+  ''
+];
+
+const WRITE_HELP = [
+  'USAGE',
+  "  chemx write <file> - [options] <<'EOF'",
+  '  whole file content',
+  '  EOF',
+  '  chemx write <file> --content="text" [options]',
+  '',
+  'OPTIONS',
+  '  -, --stdin               Read content from stdin (heredoc)',
+  '  --content=<text>         File content (also: --content <text>)',
+  '  --content-file=<path>    Read content from a file',
+  '  --overwrite              Allow replacing an existing file',
+  '  --append                 Add the content to the end of the file (created if missing); same checks as a write; not with --overwrite',
+  '  --allow-remove=<a,b>     Top-level declarations an overwrite may remove',
+  '  --allow-missing-import   Allow the write although it leaves an import unresolved',
+  '  --as=<agent>             Agent id for team lock checks',
+  '  -n, --dry-run            Print the unified diff without writing (--dryRun, --dry-run=<any> too)',
+  '  --json                   Output result as JSON',
+  '  -h, --help               Show this help message',
+  ''
+];
+
+const isHelpRequest = (args) => hasFlag(args, ['--help', '-h', 'help']);
+
+const showHelp = (args, lines, isCli) => {
+  const isJson = args.includes('--json');
+  process.stdout.write(isJson ? `${JSON.stringify({ help: true, success: true })}\n` : lines.join('\n'));
+  if (isCli) process.exit(0);
+  return { help: true, success: true };
+};
+
+const fail = (message, isCli) => {
+  process.stderr.write(`${ANSI.RED}✕ ${message}${ANSI.RESET}\n`);
+  if (isCli) process.exit(1);
+  return null;
+};
+
+const fromFileOr = (inline, filePath) => (filePath ? fs.readFileSync(filePath, 'utf-8') : inline);
+
+const printDeclarations = (res) => {
+  const removed = res.declarations?.removed || [];
+  const added = res.declarations?.added || [];
+  const hasDeclarationChange = removed.length > 0 || added.length > 0;
+  if (hasDeclarationChange) {
+    process.stdout.write(`  Declarations: removed [${removed.join(', ')}], added [${added.join(', ')}]\n`);
+  }
+};
+
+const printParseNote = (res) => {
+  const note = res.parse?.note;
+  const hasNote = Boolean(note);
+  if (hasNote) process.stdout.write(`  ${ANSI.GOLD}⚠ Parse: ${note}${ANSI.RESET}\n`);
+};
+
+const printOutcome = (res, verb, isJson) => {
+  if (isJson) {
+    process.stdout.write(`${JSON.stringify(res, null, 2)}\n`);
+    return;
+  }
+  const isPreview = Boolean(res.dryRun);
+  if (isPreview) {
+    process.stdout.write(`${ANSI.GOLD}[DRY RUN] Would ${verb} ${res.file}. No changes were written to disk.${ANSI.RESET}\n`);
+    process.stdout.write(`${res.diff || '(no change)'}\n`);
+    printDeclarations(res);
+    printParseNote(res);
+    return;
+  }
+  const range = res.changedLines ? `L${res.changedLines.start}-${res.changedLines.end}` : '';
+  const isMultiBlock = res.blocks > 1;
+  const where = isMultiBlock ? ` (${res.blocks} blocks, first at ${range})` : (range && `:${range}`);
+  const writeVerb = res.created ? 'Created' : 'Updated';
+  const doneVerb = verb === 'patch' ? 'Patched' : writeVerb;
+  process.stdout.write(`${ANSI.GREEN}✔ ${doneVerb} ${res.file}${where}${res.backup ? ` (backup: ${res.backup})` : ''}${ANSI.RESET}\n`);
+  (res.leaseNotes ?? []).forEach((note) => process.stdout.write(`  ${ANSI.GOLD}⚠ ${note}${ANSI.RESET}\n`));
+  const isOverBudget = Boolean(res.lineBudget) && !res.lineBudget.passed;
+  if (isOverBudget) {
+    process.stdout.write(`  ${ANSI.RED}⚠ Line Budget: ${res.lineBudget.lines}L exceeds ${res.lineBudget.limit}L limit (Directive 1.A)${ANSI.RESET}\n`);
+  }
+  printDeclarations(res);
+  printParseNote(res);
+  const introduced = res.introducedViolations || [];
+  const preExisting = res.preExistingViolations || [];
+  const hasIntroduced = introduced.length > 0;
+  if (hasIntroduced) {
+    process.stdout.write(`  ${ANSI.RED}⚠ ${introduced.length} introduced architecture hazard(s):${ANSI.RESET}\n`);
+    for (const h of introduced) {
+      process.stdout.write(`    [${h.severity}] line ${h.line}: ${h.hazard}\n`);
+    }
+  }
+  const hasPreExisting = preExisting.length > 0;
+  if (hasPreExisting) {
+    process.stdout.write(`  ${ANSI.DIM}  (${preExisting.length} pre-existing hazard(s))${ANSI.RESET}\n`);
+  }
+  const hasNoIntroduced = introduced.length === 0;
+  const hasNoPreExisting = preExisting.length === 0;
+  const hasNeither = hasNoIntroduced && hasNoPreExisting;
+  if (hasNeither) {
+    const hasViolations = res.violationsCount > 0;
+    if (hasViolations) {
+      process.stdout.write(`  ${ANSI.GOLD}⚠ ${res.violationsCount} architecture hazard(s) detected (Run chemx check ${res.file})${ANSI.RESET}\n`);
+    }
+  }
+};
+
+const runGuarded = (action, verb, isJson, isCli) => {
+  try {
+    const res = action();
+    printOutcome(res, verb, isJson);
+    if (isCli) process.exit(0);
+    return res;
+  } catch (err) {
+    return fail(err instanceof Error ? err.message : String(err), isCli);
+  }
+};
+
+const PATCH_FLAGS = {
+  target: ['--target'], replacement: ['--replacement', '--replace'],
+  targetFile: ['--target-file'], replacementFile: ['--replacement-file'],
+  allowRemove: ['--allow-remove'], as: ['--as']
+};
+const PATCH_SWITCHES = ['--multiple', '--allow-multiple', '--allow-missing-import'];
+const NO_PATCH_INPUT = `chemx patch needs SEARCH/REPLACE blocks on stdin (chemx patch <file> <<'EOF' ... EOF) or --target/--replacement. Nothing was changed.`;
+
+// An interactive terminal never counts as input: refusing beats blocking on, or writing, nothing.
+const readStdin = () => (isStdinTty() ? null : fs.readFileSync(0, 'utf-8'));
+
+const readStdinBlocks = () => {
+  const text = readStdin() ?? '';
+  const isEmpty = text.trim() === '';
+  if (isEmpty) throw new Error(NO_PATCH_INPUT);
+  return parseSearchReplaceBlocks(text);
+};
+
+/**
+ * Repair path for the boot shim (cli/index.js): when the CLI proper cannot load (for example a
+ * half-written commands-schema-*.js), `patch`, `edit` and `write` still run from here. This module
+ * and its imports never touch the command-schema modules. It skips the router's lease renewal and
+ * call ledger; nothing else about the edit is relaxed. Returns false for any other command.
+ */
+export const REPAIR_COMMANDS = ['patch', 'edit', 'write'];
+// `hook <name>` also runs from here (no stderr note: hosts read hook stderr), so a broken schema module
+// cannot take the guard down. The hook modules load on their own; a schema module they import breaks only that hook.
+export const runRepairCommand = async (command, args) => {
+  const isHookCommand = command === 'hook' || command === 'hooks';
+  if (isHookCommand) {
+    const { HOOKS, runHookCli } = await import('./hooks/run-hook.js');
+    const isKnownHook = Object.hasOwn(HOOKS, args[0] ?? '');
+    if (!isKnownHook) return false;
+    process.exitCode = await runHookCli(args);
+    return true;
+  }
+  const isRepairable = REPAIR_COMMANDS.includes(command);
+  if (!isRepairable) return false;
+  const run = command === 'write' ? runWriterCli : runPatcherCli;
+  run(args, true);
+  return true;
+};
+
+export const runPatcherCli = (args, isCli = false) => {
+  if (isHelpRequest(args)) return showHelp(args, PATCH_HELP, isCli);
+  const unknown = findUnknownFlags(args, [...Object.values(PATCH_FLAGS).flat(), ...PATCH_SWITCHES]);
+  const hasUnknownFlags = unknown.length > 0;
+  if (hasUnknownFlags) return fail(unknownFlagsMessage('patch', unknown), isCli);
+  const { values, positionals } = parseValueFlags(args, PATCH_FLAGS);
+  const filePath = positionals[0];
+  const hasFilePath = Boolean(filePath);
+  if (!hasFilePath) return fail('Missing file path. Usage: chemx patch <file> --target="text" --replacement="new" [--json]', isCli);
+
+  const hasInlineTarget = values.target !== undefined || values.targetFile !== undefined;
+  return runGuarded(() => patchFile(filePath, {
+    blocks: hasInlineTarget ? undefined : readStdinBlocks(),
+    targetContent: fromFileOr(values.target ?? null, values.targetFile),
+    replacementContent: fromFileOr(values.replacement ?? null, values.replacementFile),
+    allowMultiple: hasFlag(args, PATCH_SWITCHES),
+    dryRun: hasPreviewFlag(args),
+    allowRemoved: splitList(values.allowRemove),
+    allowMissingImport: args.includes('--allow-missing-import'),
+    agentId: values.as
+  }), 'patch', args.includes('--json'), isCli);
+};
+
+const WRITE_FLAGS = { content: ['--content'], contentFile: ['--content-file'], allowRemove: ['--allow-remove'], as: ['--as'] };
+const WRITE_SWITCHES = ['--stdin', '--overwrite', '--append', '--allow-missing-import'];
+const MISSING_CONTENT = 'chemx write needs --content=<text>, --content-file=<path> or --stdin (a value starting with "-" needs the --content=<text> form). Refusing to write.';
+
+const readWriteContent = (args, values) => {
+  const isStdin = args.includes('--stdin') || args.includes('-');
+  const content = isStdin ? readStdin() : fromFileOr(values.content, values.contentFile);
+  const isMissingContent = typeof content !== 'string';
+  if (isMissingContent) throw new Error(MISSING_CONTENT);
+  return content;
+};
+
+export const runWriterCli = (args, isCli = false) => {
+  if (isHelpRequest(args)) return showHelp(args, WRITE_HELP, isCli);
+  const unknown = findUnknownFlags(args, [...Object.values(WRITE_FLAGS).flat(), ...WRITE_SWITCHES]);
+  const hasUnknownFlags = unknown.length > 0;
+  if (hasUnknownFlags) return fail(unknownFlagsMessage('write', unknown), isCli);
+  const { values, positionals } = parseValueFlags(args, WRITE_FLAGS);
+  const filePath = positionals[0];
+  const hasFilePath = Boolean(filePath);
+  if (!hasFilePath) return fail('Missing file path. Usage: chemx write <file> --content="text" [--json]', isCli);
+
+  return runGuarded(() => writeOrAppend(filePath, {
+    content: readWriteContent(args, values),
+    overwrite: args.includes('--overwrite'),
+    append: args.includes('--append'),
+    dryRun: hasPreviewFlag(args),
+    allowRemoved: splitList(values.allowRemove),
+    allowMissingImport: args.includes('--allow-missing-import'),
+    agentId: values.as
+  }), 'write', args.includes('--json'), isCli);
+};

package/cli/patcher.d.ts

@@ -1,10 +1,27 @@
-export interface PatchOptions {
-  readonly targetContent: string;
-  readonly replacementContent: string;
-  readonly allowMultiple?: boolean;
+export interface MutationSafetyOptions {
   readonly cwd?: string;
   readonly skipIndex?: boolean;
   readonly skipCheck?: boolean;
+  /** Validate and diff without writing. */
+  readonly dryRun?: boolean;
+  /** Top-level declarations this edit may remove (a net loss is otherwise refused). */
+  readonly allowRemoved?: readonly string[];
+  /** Caller identity for team lock checks (default $CHEMX_AGENT_ID, else '@agent'). */
+  readonly agentId?: string;
+}
+
+export interface SearchReplaceBlock {
+  readonly search: string;
+  readonly replace: string;
+}
+
+export interface PatchOptions extends MutationSafetyOptions {
+  /** Required unless blocks is given. */
+  readonly targetContent?: string;
+  readonly replacementContent?: string;
+  /** Applied in order to one copy; any unmatched block fails the call and writes nothing. */
+  readonly blocks?: readonly SearchReplaceBlock[];
+  readonly allowMultiple?: boolean;
 }
 
 export interface LineBudgetResult {
@@ -14,14 +31,12 @@ export interface LineBudgetResult {
   readonly warning: string | null;
 }
 
-export interface PatchResult {
-  readonly file: string;
-  readonly status: 'ok';
-  readonly replaced: number | 'all';
-  readonly originalLines: number;
-  readonly newLines: number;
-  readonly lineDelta: number;
-  readonly indexed: boolean;
+export interface DeclarationDelta {
+  readonly removed: readonly string[];
+  readonly added: readonly string[];
+}
+
+export interface GuardrailResult {
   readonly lineBudget: LineBudgetResult;
   readonly isClean: boolean;
   readonly violationsCount: number;
@@ -30,6 +45,26 @@ export interface PatchResult {
   readonly violations: readonly any[];
 }
 
+export interface PatchResult extends GuardrailResult {
+  readonly file: string;
+  readonly status: 'ok';
+  readonly dryRun: boolean;
+  readonly replaced: number;
+  /** Number of SEARCH/REPLACE blocks applied (only for a blocks patch). */
+  readonly blocks?: number;
+  readonly matchLines: readonly number[];
+  readonly changedLines: { readonly start: number; readonly end: number };
+  readonly eol: 'as-is' | 'crlf-normalized';
+  readonly originalLines: number;
+  readonly newLines: number;
+  readonly lineDelta: number;
+  readonly indexed: boolean;
+  readonly backup: string | null;
+  readonly declarations: DeclarationDelta;
+  /** Uncapped unified diff of the change. */
+  readonly diff: string;
+}
+
 export declare function patchFile(
   targetPath: string,
   params: PatchOptions
@@ -40,25 +75,22 @@ export declare function runPatcherCli(
   isCli?: boolean
 ): PatchResult | null;
 
-export interface WriteOptions {
+export interface WriteOptions extends MutationSafetyOptions {
   readonly content: string;
-  readonly cwd?: string;
-  readonly skipIndex?: boolean;
-  readonly skipCheck?: boolean;
+  /** Required to replace an existing file. */
+  readonly overwrite?: boolean;
 }
 
-export interface WriteResult {
+export interface WriteResult extends GuardrailResult {
   readonly file: string;
   readonly status: 'ok';
+  readonly dryRun: boolean;
   readonly created: boolean;
   readonly lines: number;
   readonly indexed: boolean;
-  readonly lineBudget: LineBudgetResult;
-  readonly isClean: boolean;
-  readonly violationsCount: number;
-  readonly criticalCount: number;
-  readonly highCount: number;
-  readonly violations: readonly any[];
+  readonly backup: string | null;
+  readonly declarations: DeclarationDelta;
+  readonly diff: string;
 }
 
 export declare function writeFile(
@@ -70,4 +102,3 @@ export declare function runWriterCli(
   args: readonly string[],
   isCli?: boolean
 ): WriteResult | null;
-