cans-spec 0.1.1 → 0.2.0

package/README.md

@@ -169,7 +169,15 @@ This is the most important section.
 
 ## Install
 
-Requires [Bun](https://bun.sh) ≥ 1.0 on your PATH (the CLI runs on the Bun runtime). No build step. Source IS distribution.
+No build step. Source IS distribution. Two runtimes are supported — Bun is the
+primary, Node.js is the fallback (issue #12):
+
+- **Bun ≥ 1.0 (recommended, primary)** — fastest path, used automatically when
+  Bun is on your PATH.
+- **Node.js ≥ 23.2 (fallback)** — for Termux / Android harnesses and any
+  environment without Bun. Termux: `pkg install nodejs` (ships Node 26.x ✓).
+  Node's builtin TypeScript stripping runs the sources directly; running from
+  a source checkout also works on Node ≥ 22.6 via `--experimental-strip-types`.
 
 **npm**
 
@@ -187,6 +195,8 @@ bun install -g cans-spec
 
 ```bash
 npx -p cans-spec cans init
+# or, with Bun installed:
+bunx cans-spec init
 ```
 
 All three give you the same `cans` command:
@@ -315,19 +325,21 @@ cans/
 
 ## Requirements
 
-- [Bun](https://bun.sh) ≥ 1.0
+- [Bun](https://bun.sh) ≥ 1.0 (primary) **or** Node.js ≥ 23.2 (fallback, no Bun needed — Termux: `pkg install nodejs`)
 - Git (for coordination; not required by CANS itself)
 - An AI agent that can read markdown (all of them)
 
-No Node.js. No Python. No `package-lock.json`. No `node_modules`. The `dependencies` field in `package.json` does not exist.
+No Python. No `package-lock.json`. No build step. The `dependencies` field in `package.json` does not exist — zero runtime dependencies on both runtimes.
 
 ---
 
 ## Contributing
 
-The entire codebase is ~1080 lines of TypeScript across 20 files. Read it in an afternoon.
+The entire codebase is ~1100 lines of TypeScript across 20 files. Read it in an afternoon.
 
-- `bun test` runs the suite (~95 tests)
+- `bun test` runs the suite on the primary runtime; `npm run test:node` runs the same suite on the Node fallback (node:test via a tiny bun:test compat shim in `test/node-compat.ts`)
+- CI runs both (`test-bun` + `test-node` matrix on Node 22/24)
+- All runtime-sensitive IO goes through one shim, `src/core/runtime.ts` — the only file allowed to touch Bun APIs; a self-audit test keeps it that way
 - No build step. Edit `src/`, run `bun test`, done.
 - PRs that add features get closed. PRs that delete code get merged.
 - If you want a new command, open an issue and justify it. Most get rejected. That's the point.

package/bin/cans.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+/**
+ * Portable launcher for the `cans` bin (issue #12).
+ *
+ * Priority: Bun stays the primary runtime.
+ *   1. Already executing under Bun (`bunx cans-spec`, `bun run`) → run the CLI
+ *      in-process; the runtime shim's Bun fast paths apply.
+ *   2. Bun on PATH but this launcher was started by Node (`npm i -g cans-spec`
+ *      then `cans ...`) → re-exec `bun src/cli.ts` so Bun fast paths apply.
+ *   3. No Bun → run the CLI in-process on Node, stripping TypeScript via
+ *      Node's builtin `stripTypeScriptTypes` through bin/ts-loader.mjs (Node's
+ *      default stripping refuses files under node_modules — see issue #12 QA).
+ *
+ * This file is plain JavaScript ON PURPOSE: it must execute on any Node that
+ * npm can provide, before any TypeScript capability is available.
+ */
+import { spawnSync } from 'node:child_process';
+import { register } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cli = join(here, '..', 'src', 'cli.ts');
+const args = process.argv.slice(2);
+
+/** Run cli.ts in the current process; it calls process.exit() itself, but a
+ *  load-time failure (unreadable package.json, syntax) must still report. */
+async function runInProcess() {
+  try {
+    await import(pathToFileURL(cli).href);
+    process.exit(process.exitCode ?? 0);
+  } catch (e) {
+    console.error(`✗ Internal error: ${e instanceof Error ? e.message : e}`);
+    process.exit(2);
+  }
+}
+
+// 1. Already under Bun — in-process, Bun fast paths.
+if (typeof globalThis.Bun !== 'undefined') {
+  await runInProcess();
+}
+
+// 2. Bun on PATH — re-exec so Bun stays the primary runtime.
+const probe = spawnSync('bun', ['--version'], { stdio: 'ignore' });
+if (!probe.error && probe.status === 0) {
+  const r = spawnSync('bun', [cli, ...args], { stdio: 'inherit' });
+  if (r.error) {
+    console.error(`✗ Internal error: failed to launch bun: ${r.error.message}`);
+    process.exit(2);
+  }
+  process.exit(r.status ?? 130);
+}
+
+// 3. Node fallback — needs node:module.stripTypeScriptTypes (Node ≥23.2; made
+//    stable in 23.6). Termux `pkg install nodejs` ships 26.x, which qualifies.
+//    Namespace access (not a named import) so older Nodes link this file fine.
+const { stripTypeScriptTypes } = await import('node:module');
+if (typeof stripTypeScriptTypes !== 'function') {
+  console.error(
+    `✗ cans requires Bun >= 1.0 (primary) or Node >= 23.2 with builtin TypeScript stripping; found Node ${process.versions.node} without Bun.`,
+  );
+  console.error('  Install Bun: https://bun.sh — Termux: pkg install nodejs.');
+  process.exit(1);
+}
+
+// Node prints an ExperimentalWarning for stripTypeScriptTypes on every run;
+// suppress just that one and pass everything else through untouched.
+process.removeAllListeners('warning');
+process.on('warning', (w) => {
+  if (w && w.name === 'ExperimentalWarning' && String(w.message).includes('stripTypeScriptTypes')) return;
+  console.error(`(node:${process.pid}) [${w?.name ?? 'Warning'}] ${w?.message ?? w}`);
+});
+
+// 4. Register the .ts loader hook, then execute the CLI in-process.
+register(new URL('./ts-loader.mjs', import.meta.url));
+await runInProcess();

package/bin/ts-loader.mjs

@@ -0,0 +1,34 @@
+/**
+ * ESM loader hook for the Node fallback runtime (issue #12).
+ *
+ * Node's built-in TypeScript type-stripping refuses to process files under
+ * `node_modules`, which breaks `npm i -g cans-spec` on machines without Bun —
+ * the exact Termux scenario this package must support. This hook performs the
+ * SAME erasable-syntax stripping ourselves via Node's builtin
+ * `node:module.stripTypeScriptTypes` (no dependencies, no build step — source
+ * stays distribution), bypassing only that path-based veto.
+ */
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import { stripTypeScriptTypes } from 'node:module';
+
+// This hook runs inside Node's loader thread, whose default handler prints the
+// `stripTypeScriptTypes` ExperimentalWarning on every CLI run. Suppress warnings
+// scoped to THIS thread only (CANS_DEBUG_WARNINGS=1 restores them).
+if (process.env.CANS_DEBUG_WARNINGS !== '1') {
+  process.removeAllListeners('warning');
+  process.on('warning', () => {});
+}
+
+export async function load(url, context, nextLoad) {
+  if (url.endsWith('.ts')) {
+    const file = fileURLToPath(url);
+    const code = await readFile(file, 'utf8');
+    // Node ≥23.2 returns an object ({ source }); some versions return the
+    // stripped string directly — accept both shapes.
+    const result = stripTypeScriptTypes(code, { sourceUrl: file });
+    const source = typeof result === 'string' ? result : result?.source;
+    return { format: 'module', source, shortCircuit: true };
+  }
+  return nextLoad(url, context);
+}

package/package.json

@@ -1,20 +1,23 @@
 {
   "name": "cans-spec",
-  "version": "0.1.1",
-  "description": "Canonical Agent-Native Spec — the outline is the spec, the state, and the task board",
+  "version": "0.2.0",
+  "description": "Canonical Agent-Native Spec \u2014 the outline is the spec, the state, and the task board",
   "bin": {
-    "cans": "./src/cli.ts"
+    "cans": "./bin/cans.js"
   },
   "type": "module",
   "engines": {
-    "bun": ">=1.0.0"
+    "bun": ">=1.0.0",
+    "node": ">=23.2.0"
   },
   "scripts": {
-    "typecheck": "bunx tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "test": "bun test",
-    "prepublishOnly": "bun run typecheck && bun test"
+    "test:node": "node --test --experimental-strip-types \"test/**/*.test.ts\"",
+    "prepublishOnly": "npm run typecheck && bun test"
   },
   "files": [
+    "bin/",
     "src/",
     "templates/",
     "README.md",

package/src/cli.ts

@@ -1,23 +1,28 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 
-import type { CommandResult } from './types';
-import { emit } from './core/output';
+import type { CommandResult } from './types.ts';
+import { emit } from './core/output.ts';
+import { argv, readText, dirFromUrl } from './core/runtime.ts';
+import { join } from 'node:path';
 
-/** §44: version line. Keep in sync with package.json. */
-const VERSION = '0.1.0';
+/** §44: version line — derived from package.json so it can never drift.
+ *  Read through the runtime shim (issue #12): a bare JSON import has no
+ *  import attributes and is therefore not portable to the Node fallback. */
+const PKG_FILE = join(dirFromUrl(import.meta.url), '..', 'package.json');
+const VERSION: string = (JSON.parse(await readText(PKG_FILE)) as { version: string }).version;
 
-const [cmd, ...args] = Bun.argv.slice(2);
+const [cmd, ...args] = argv();
 
 async function dispatch(): Promise<CommandResult> {
   switch (cmd) {
-    case 'init':    return (await import('./commands/init')).run(args);
-    case 'check':   return (await import('./commands/check')).run(args);
-    case 'new':     return (await import('./commands/new')).run(args);
-    case 'done':    return (await import('./commands/done')).run(args);
-    case 'status':  return (await import('./commands/status')).run(args);
-    case 'budget':  return (await import('./commands/budget')).run(args);
-    case 'import':  return (await import('./commands/import')).run(args);
-    case 'export':  return (await import('./commands/export')).run(args);
+    case 'init':    return (await import('./commands/init.ts')).run(args);
+    case 'check':   return (await import('./commands/check.ts')).run(args);
+    case 'new':     return (await import('./commands/new.ts')).run(args);
+    case 'done':    return (await import('./commands/done.ts')).run(args);
+    case 'status':  return (await import('./commands/status.ts')).run(args);
+    case 'budget':  return (await import('./commands/budget.ts')).run(args);
+    case 'import':  return (await import('./commands/import.ts')).run(args);
+    case 'export':  return (await import('./commands/export.ts')).run(args);
     case 'help':
     case '-h':      // §20/§44: conventional help shortcuts
     case '--help':

package/src/commands/budget.ts

@@ -1,10 +1,11 @@
 import { join, basename } from 'path';
-import type { BudgetReadResult, BudgetWriteResult, OutlineNode, Rules } from '../types';
-import { resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks, dirExists } from '../core/fs';
-import { parseOutline } from '../core/outline';
-import { loadRules } from '../core/rules';
-import { buildRefGraph } from '../core/refs';
-import { buildReadPlan, buildWritePlan } from '../core/token-budget';
+import type { BudgetReadResult, BudgetWriteResult, OutlineNode, Rules } from '../types.ts';
+import { readText } from '../core/runtime.ts';
+import { resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks, dirExists } from '../core/fs.ts';
+import { parseOutline } from '../core/outline.ts';
+import { loadRules } from '../core/rules.ts';
+import { buildRefGraph } from '../core/refs.ts';
+import { buildReadPlan, buildWritePlan } from '../core/token-budget.ts';
 
 export interface BudgetArgs {
   mode: 'read' | 'write';
@@ -164,7 +165,7 @@ export async function run(args: string[]): Promise<BudgetReadResult | BudgetWrit
   const files = new Map<string, OutlineNode[]>();
   for (const rel of discoverSpecFiles(workspace)) {
     try {
-      files.set(rel, parseOutline(await Bun.file(join(workspace, rel)).text(), rel));
+      files.set(rel, parseOutline(await readText(join(workspace, rel)), rel));
     } catch {
       // unreadable spec file: excluded from the plan
     }

package/src/commands/check.ts

@@ -1,23 +1,24 @@
 import { join } from 'path';
-import type { CheckResult, Issue, OutlineNode } from '../types';
+import type { CheckResult, Issue, OutlineNode } from '../types.ts';
+import { readText, writeText } from '../core/runtime.ts';
 import {
   discoverSpecFiles, discoverActiveTasks, discoverAdrs, resolveWorkspaceRoot,
   dirExists, detectFlatFolderConflicts, detectMalformedSpecDirs, discoverOverflowTargets,
-} from '../core/fs';
+} from '../core/fs.ts';
 import {
   parseOutline, extractBackPointers, flattenNodes, maxDepth as outlineMaxDepth,
   type ParseWarning,
-} from '../core/outline';
-import { loadRules } from '../core/rules';
-import { checkStructure, checkTbdPolicy } from '../core/structure';
-import { checkStyle } from '../core/style';
-import { checkOverflow, checkNoChaining } from '../core/overflow';
-import { checkRedundancy } from '../core/redundancy';
+} from '../core/outline.ts';
+import { loadRules } from '../core/rules.ts';
+import { checkStructure, checkTbdPolicy } from '../core/structure.ts';
+import { checkStyle } from '../core/style.ts';
+import { checkOverflow, checkNoChaining } from '../core/overflow.ts';
+import { checkRedundancy } from '../core/redundancy.ts';
 import {
   buildRefGraph, checkRefs, detectDeepHops, detectOrphans,
   rebuildBackPointers, targetMatchesKey,
-} from '../core/refs';
-import { parseArgs, formatArgErrors, type FlagSpec } from '../core/args';
+} from '../core/refs.ts';
+import { parseArgs, formatArgErrors, type FlagSpec } from '../core/args.ts';
 
 export interface CheckArgs {
   fix: boolean;
@@ -181,7 +182,7 @@ export async function checkWorkspace(root: string, opts: CheckArgs): Promise<Che
   for (const rel of specRel) {
     let text = '';
     try {
-      text = await Bun.file(join(root, rel)).text();
+      text = await readText(join(root, rel));
     } catch (e) {
       issues.push({
         file: rel, line: 0, level: 'error', category: 'structure',
@@ -212,7 +213,7 @@ export async function checkWorkspace(root: string, opts: CheckArgs): Promise<Che
   const auxFiles = new Map<string, OutlineNode[]>();
   for (const rel of [...safeActiveTasks(root), ...safeAdrs(root)]) {
     try {
-      const text = await Bun.file(join(root, rel)).text();
+      const text = await readText(join(root, rel));
       auxFiles.set(rel, parseOutline(text, rel));
     } catch {
       // unreadable/unparseable aux file: its refs are simply not counted
@@ -308,7 +309,7 @@ export async function checkWorkspace(root: string, opts: CheckArgs): Promise<Che
     const targetFiles = new Map<string, OutlineNode[]>();
     for (const rel of discoverOverflowTargets(root)) {
       try {
-        targetFiles.set(rel, parseOutline(await Bun.file(join(root, rel)).text(), rel));
+        targetFiles.set(rel, parseOutline(await readText(join(root, rel)), rel));
       } catch {
         // unreadable overflow target: skipped
       }
@@ -326,7 +327,7 @@ export async function checkWorkspace(root: string, opts: CheckArgs): Promise<Che
       const body = desired.get(rel) ?? null;
       const rewritten = rewriteRefBy(source, body);
       if (rewritten !== source) {
-        await Bun.write(join(root, rel), rewritten);
+        await writeText(join(root, rel), rewritten);
         specSources.set(rel, rewritten);
         backPointersUpdated++;
       }

package/src/commands/done.ts

@@ -1,10 +1,11 @@
 import { join } from 'path';
 import { renameSync } from 'fs';
-import type { DoneResult, OutlineNode } from '../types';
-import { resolveWorkspaceRoot, mkdirp, isFile, dirExists, globFiles } from '../core/fs';
-import { parseOutline, flattenNodes } from '../core/outline';
-import { checkWorkspace, type CheckArgs } from './check';
-import { parseArgs, type FlagSpec } from '../core/args';
+import type { DoneResult, OutlineNode } from '../types.ts';
+import { readText } from '../core/runtime.ts';
+import { resolveWorkspaceRoot, mkdirp, isFile, dirExists, globFiles } from '../core/fs.ts';
+import { parseOutline, flattenNodes } from '../core/outline.ts';
+import { checkWorkspace, type CheckArgs } from './check.ts';
+import { parseArgs, type FlagSpec } from '../core/args.ts';
 
 export interface DoneArgs {
   name: string;
@@ -105,7 +106,7 @@ export async function run(args: string[]): Promise<DoneResult> {
   let taskNodes: OutlineNode[] = [];
   let flat: OutlineNode[] = [];
   try {
-    taskNodes = parseOutline(await Bun.file(taskFile).text(), `_tasks/${name}.md`);
+    taskNodes = parseOutline(await readText(taskFile), `_tasks/${name}.md`);
     flat = flattenNodes(taskNodes);
   } catch {
     return failResult(name, `cannot parse _tasks/${name}.md — check for tab indentation or malformed content`);

package/src/commands/export.ts

@@ -1,13 +1,14 @@
 import { join, basename, relative } from 'path';
-import type { ExportResult, ExportFormat, OutlineNode, ExternalNode } from '../types';
+import type { ExportResult, ExportFormat, OutlineNode, ExternalNode } from '../types.ts';
+import { readText, writeText } from '../core/runtime.ts';
 import {
   resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks, discoverAdrs,
   mkdirp, dirExists, exists,
-} from '../core/fs';
-import { parseOutline } from '../core/outline';
-import { serializeOpml } from '../converters/opml';
-import { serializeLogseq } from '../converters/logseq';
-import { serializeObsidian } from '../converters/obsidian';
+} from '../core/fs.ts';
+import { parseOutline } from '../core/outline.ts';
+import { serializeOpml } from '../converters/opml.ts';
+import { serializeLogseq } from '../converters/logseq.ts';
+import { serializeObsidian } from '../converters/obsidian.ts';
 
 export interface ExportArgs {
   format: ExportFormat;
@@ -185,7 +186,7 @@ export async function run(args: string[]): Promise<ExportResult> {
     for (const rel of sources) {
       let text = '';
       try {
-        text = await Bun.file(join(workspace, rel)).text();
+        text = await readText(join(workspace, rel));
       } catch {
         continue;
       }
@@ -202,7 +203,7 @@ export async function run(args: string[]): Promise<ExportResult> {
       if (!opts.dryRun) {
         try {
           mkdirp(fmtDir);
-          await Bun.write(join(fmtDir, outputFileName(rel, f)), content);
+          await writeText(join(fmtDir, outputFileName(rel, f)), content);
         } catch (e) {
           const code = (e as NodeJS.ErrnoException | null)?.code;
           if (code === 'ENOTDIR' || code === 'EEXIST') return notDirError(fmtDir);

package/src/commands/import.ts

@@ -2,15 +2,16 @@ import { join, basename, dirname } from 'path';
 import { readdirSync } from 'fs';
 import type {
   ImportResult, ImportFormat, ImportConflict, MergeStrategy, ExternalNode,
-} from '../types';
-import { resolveWorkspaceRoot, discoverSpecFiles, mkdirp, isFile, dirExists } from '../core/fs';
-import { convertArrowRefs, parseOpml, parseOpmlTitle } from '../converters/opml';
-import { parseLogseq } from '../converters/logseq';
-import { parseObsidian, stripFrontmatter } from '../converters/obsidian';
+} from '../types.ts';
+import { readText, writeText } from '../core/runtime.ts';
+import { resolveWorkspaceRoot, discoverSpecFiles, mkdirp, isFile, dirExists } from '../core/fs.ts';
+import { convertArrowRefs, parseOpml, parseOpmlTitle } from '../converters/opml.ts';
+import { parseLogseq } from '../converters/logseq.ts';
+import { parseObsidian, stripFrontmatter } from '../converters/obsidian.ts';
 import {
   serializeToCans, parseFromCans, stripMetadata, parseCheckbox,
   extractOverflowContent, type OverflowExtraction,
-} from '../converters/shared';
+} from '../converters/shared.ts';
 
 export interface ImportArgs {
   format: ImportFormat;
@@ -325,7 +326,7 @@ async function findExistingByRootText(targetDir: string, imported: ExternalNode[
   for (const rel of discoverSpecFiles(targetDir)) {
     let text = '';
     try {
-      text = await Bun.file(join(targetDir, rel)).text();
+      text = await readText(join(targetDir, rel));
     } catch {
       continue;
     }
@@ -400,7 +401,7 @@ export async function run(args: string[]): Promise<ImportResult> {
   for (const src of files) {
     let text = '';
     try {
-      text = await Bun.file(src).text();
+      text = await readText(src);
     } catch {
       continue;
     }
@@ -454,7 +455,7 @@ export async function run(args: string[]): Promise<ImportResult> {
     if (existingRel !== null) {
       const absTarget = join(workspace, existingRel);
       const outcome = mergeInto(
-        await Bun.file(absTarget).text(),
+        await readText(absTarget),
         imported,
         opts.mergeStrategy,
         existingRel,
@@ -462,11 +463,11 @@ export async function run(args: string[]): Promise<ImportResult> {
       conflicts.push(...outcome.conflicts);
       if (outcome.content !== null) {
         if (!opts.dryRun) {
-          await Bun.write(absTarget, canonicalizeRefTargets(outcome.content));
+          await writeText(absTarget, canonicalizeRefTargets(outcome.content));
           for (const ovf of overflow) {
             const ovfAbs = join(workspace, ovf.overflowFile);
             mkdirp(dirname(ovfAbs));
-            await Bun.write(ovfAbs, `${ovf.content}\n`);
+            await writeText(ovfAbs, `${ovf.content}\n`);
           }
         }
         merged.push(existingRel);
@@ -485,11 +486,11 @@ export async function run(args: string[]): Promise<ImportResult> {
     const cansText = canonicalizeRefTargets(serializeToCans(imported));
     if (!opts.dryRun) {
       mkdirp(dirname(absTarget));
-      await Bun.write(absTarget, cansText);
+      await writeText(absTarget, cansText);
       for (const ovf of overflow) {
         const ovfAbs = join(workspace, ovf.overflowFile);
         mkdirp(dirname(ovfAbs));
-        await Bun.write(ovfAbs, `${ovf.content}\n`);
+        await writeText(ovfAbs, `${ovf.content}\n`);
       }
     }
     newFiles.push(relName);

package/src/commands/init.ts

@@ -1,12 +1,13 @@
 import { basename, dirname, join, relative } from 'path';
-import type { InitResult } from '../types';
-import { resolveWorkspaceRoot, resolveInitTarget, mkdirp, exists, dirExists } from '../core/fs';
-import { parseArgs, type FlagSpec } from '../core/args';
+import type { InitResult } from '../types.ts';
+import { readText, writeText, dirFromUrl } from '../core/runtime.ts';
+import { resolveWorkspaceRoot, resolveInitTarget, mkdirp, exists, dirExists } from '../core/fs.ts';
+import { parseArgs, type FlagSpec } from '../core/args.ts';
 
-const TEMPLATES_DIR = join(import.meta.dir, '..', '..', 'templates');
+const TEMPLATES_DIR = join(dirFromUrl(import.meta.url), '..', '..', 'templates');
 
 async function readTemplate(name: string): Promise<string> {
-  return await Bun.file(join(TEMPLATES_DIR, name)).text();
+  return await readText(join(TEMPLATES_DIR, name));
 }
 
 export interface InitArgs {
@@ -168,7 +169,7 @@ export async function run(args: string[]): Promise<InitResult> {
       skipped.push(entry.path);
       continue;
     }
-    await Bun.write(abs, entry.content ?? '');
+    await writeText(abs, entry.content ?? '');
     created.push(entry.path);
   }
 

package/src/commands/new.ts

@@ -1,12 +1,13 @@
 import { join, basename } from 'path';
-import type { NewResult } from '../types';
-import { resolveWorkspaceRoot, resolveWorkspaceOrCreate, mkdirp, discoverAdrs, dirExists, isFile } from '../core/fs';
-import { parseArgs, type FlagSpec } from '../core/args';
+import type { NewResult } from '../types.ts';
+import { readText, writeText, dirFromUrl } from '../core/runtime.ts';
+import { resolveWorkspaceRoot, resolveWorkspaceOrCreate, mkdirp, discoverAdrs, dirExists, isFile } from '../core/fs.ts';
+import { parseArgs, type FlagSpec } from '../core/args.ts';
 
-const TEMPLATES_DIR = join(import.meta.dir, '..', '..', 'templates');
+const TEMPLATES_DIR = join(dirFromUrl(import.meta.url), '..', '..', 'templates');
 
 async function readTemplate(name: string): Promise<string> {
-  return await Bun.file(join(TEMPLATES_DIR, name)).text();
+  return await readText(join(TEMPLATES_DIR, name));
 }
 
 /** lowercase → strip double quotes → non-alphanumeric runs → hyphens → trim hyphens.
@@ -58,7 +59,7 @@ async function existingContentGuard(
   change: string,
 ): Promise<NewResult | null> {
   if (!isFile(abs)) return null;
-  const existing = await Bun.file(abs).text();
+  const existing = await readText(abs);
   if (existing === content) {
     return { ok: true, command: 'new', exitCode: 0, change, file };
   }
@@ -116,7 +117,7 @@ export async function run(args: string[]): Promise<NewResult> {
     const file = join('_tasks', `${slug}.md`);
     const guard = await existingContentGuard(join(workspace, file), file, content, slug);
     if (guard !== null) return guard;
-    await Bun.write(join(workspace, file), content);
+    await writeText(join(workspace, file), content);
     return { ok: true, command: 'new', exitCode: 0, change: slug, file };
   }
 
@@ -133,6 +134,6 @@ export async function run(args: string[]): Promise<NewResult> {
   const file = join('_adr', `${NNN}-${slug}.md`);
   const guard = await existingContentGuard(join(workspace, file), file, content, slug);
   if (guard !== null) return guard;
-  await Bun.write(join(workspace, file), content);
+  await writeText(join(workspace, file), content);
   return { ok: true, command: 'new', exitCode: 0, change: slug, file };
 }

package/src/commands/status.ts

@@ -1,12 +1,13 @@
 import { join, basename } from 'path';
 import { readFileSync } from 'fs';
-import type { StatusResult, OutlineNode } from '../types';
+import type { StatusResult, OutlineNode } from '../types.ts';
+import { readText } from '../core/runtime.ts';
 import {
   resolveWorkspaceRoot, discoverSpecFiles, discoverActiveTasks,
   discoverArchivedTasks, discoverAdrs, dirExists,
-} from '../core/fs';
-import { parseOutline, flattenNodes } from '../core/outline';
-import { parseArgs, type FlagSpec } from '../core/args';
+} from '../core/fs.ts';
+import { parseOutline, flattenNodes } from '../core/outline.ts';
+import { parseArgs, type FlagSpec } from '../core/args.ts';
 
 export interface StatusArgs {
   unclaimed: boolean;
@@ -100,7 +101,7 @@ export async function run(args: string[]): Promise<StatusResult> {
   for (const rel of activeTasks) {
     let flat: OutlineNode[] = [];
     try {
-      flat = flattenNodes(parseOutline(await Bun.file(join(workspace, rel)).text(), rel));
+      flat = flattenNodes(parseOutline(await readText(join(workspace, rel)), rel));
     } catch {
       // unparsable task file: contributes nothing but its existence
     }

package/src/converters/index.ts

@@ -1,4 +1,4 @@
-export * from './shared';
-export * from './opml';
-export * from './logseq';
-export * from './obsidian';
+export * from './shared.ts';
+export * from './opml.ts';
+export * from './logseq.ts';
+export * from './obsidian.ts';

package/src/converters/logseq.ts

@@ -1,8 +1,8 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 import {
   convertOwnerMarkers, convertWikiLinks, logseqSlashLinks, parseCheckbox,
   parseIndent, reverseWikiLinks, stripMetadata,
-} from './shared';
+} from './shared.ts';
 
 /** Logseq page → flat ExternalNode list (document order; hierarchy via `indent`).
  *  Drops pure `key:: value` property lines (keys may contain spaces — only `::`

package/src/converters/obsidian.ts

@@ -1,8 +1,8 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 import {
   convertOwnerMarkers, convertWikiLinks, parseCheckbox, parseIndent,
   reverseWikiLinks, stripMetadata,
-} from './shared';
+} from './shared.ts';
 
 /** Remove a leading YAML frontmatter block (`---` fences at very top), fences included. */
 export function stripFrontmatter(source: string): string {

package/src/converters/opml.ts

@@ -1,4 +1,4 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 
 /** Escape the five XML entities. `&` first so output is never double-encoded. */
 export function encodeXmlEntity(s: string): string {

package/src/converters/shared.ts

@@ -1,4 +1,4 @@
-import type { ExternalNode } from '../types';
+import type { ExternalNode } from '../types.ts';
 
 /** Leading whitespace → indent units. 2 spaces per level; each tab counts as 2 spaces. */
 export function parseIndent(raw: string): number {

package/src/core/fs.ts

@@ -1,5 +1,6 @@
 import { statSync, readdirSync, existsSync, mkdirSync, type Stats } from 'fs';
 import { join, relative, dirname, basename } from 'path';
+import { globFiles as runtimeGlobFiles } from './runtime.ts';
 
 const SPEC_FILE_RE = /^\d{2}-.+\.md$/;
 
@@ -26,10 +27,8 @@ export function mkdirp(p: string): void {
 }
 
 export function globFiles(dir: string, pattern: string): string[] {
-  if (!dirExists(dir)) return [];
-  const g = new Bun.Glob(pattern);
-  const out = [...g.scanSync({ cwd: dir, onlyFiles: true })] as string[];
-  return out.sort();
+  // Delegated to the runtime shim (issue #12): Bun fast path, node:fs fallback.
+  return runtimeGlobFiles(dir, pattern);
 }
 
 /** Spec files: root-level *.md (excluding _-prefixed, AGENTS.md and other tool

package/src/core/index.ts

@@ -1,10 +1,10 @@
-export * from './output';
-export * from './fs';
-export * from './outline';
-export * from './refs';
-export * from './structure';
-export * from './style';
-export * from './redundancy';
-export * from './overflow';
-export * from './rules';
-export * from './token-budget';
+export * from './output.ts';
+export * from './fs.ts';
+export * from './outline.ts';
+export * from './refs.ts';
+export * from './structure.ts';
+export * from './style.ts';
+export * from './redundancy.ts';
+export * from './overflow.ts';
+export * from './rules.ts';
+export * from './token-budget.ts';

package/src/core/outline.ts

@@ -1,4 +1,4 @@
-import type { OutlineNode, BackPointer, RefTarget } from '../types';
+import type { OutlineNode, BackPointer, RefTarget } from '../types.ts';
 
 const BULLET_RE = /^(\s*)-\s+(.*)$/;
 const CHECKBOX_RE = /^\[( |x|X)\]\s+/;

package/src/core/output.ts

@@ -1,7 +1,7 @@
 import type {
   CommandResult, CheckResult, Issue, InitResult, NewResult, DoneResult, StatusResult,
   BudgetReadResult, BudgetWriteResult, ImportResult, ExportResult, VersionResult,
-} from '../types';
+} from '../types.ts';
 
 /** Single emission point. Commands never console.log or process.exit directly.
  *  `refsOnly` (check only, §22/§36): human output is scoped to the References

package/src/core/overflow.ts

@@ -1,5 +1,5 @@
-import type { OutlineNode, Issue, OverflowRules } from '../types';
-import { flattenNodes } from './outline';
+import type { OutlineNode, Issue, OverflowRules } from '../types.ts';
+import { flattenNodes } from './outline.ts';
 
 /** Overflow checks: code fences, tables, over-long nodes. All errors.
  *  §18: `force_file_for` lists the content categories forced into files —

package/src/core/redundancy.ts

@@ -1,5 +1,5 @@
-import type { OutlineNode, Issue, RedundancyRules } from '../types';
-import { flattenNodes } from './outline';
+import type { OutlineNode, Issue, RedundancyRules } from '../types.ts';
+import { flattenNodes } from './outline.ts';
 
 interface NodeRef {
   text: string;

package/src/core/refs.ts

@@ -1,8 +1,8 @@
 import { readFileSync } from 'fs';
 import { join } from 'path';
-import type { OutlineNode, RefTarget, BackPointer, Issue } from '../types';
-import { flattenNodes, parseOutline } from './outline';
-import { resolveSpecFile, toRelative, isFile } from './fs';
+import type { OutlineNode, RefTarget, BackPointer, Issue } from '../types.ts';
+import { flattenNodes, parseOutline } from './outline.ts';
+import { resolveSpecFile, toRelative, isFile } from './fs.ts';
 
 export interface RefGraph {
   forward: Map<string, RefTarget[]>;

package/src/core/rules.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { Rules } from '../types';
+import type { Rules } from '../types.ts';
 
 interface YLine {
   lineNo: number;

package/src/core/runtime.ts

@@ -0,0 +1,110 @@
+/** Runtime shim — the ONLY module allowed to touch `Bun.*` APIs (issue #12).
+ *
+ *  Bun stays the primary runtime (fast path, behavior byte-identical to the
+ *  pre-#12 code); Node.js ≥22.6 is the fallback (Termux / no-Bun harnesses).
+ *  The Node path uses only `node:` builtins — the zero-dependency law holds on
+ *  both runtimes. Anything outside this module that needs a runtime-sensitive
+ *  operation MUST go through one of these exports; a repo self-audit test
+ *  (test/node-fallback.test.ts) enforces `Bun\.` never appears elsewhere.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Minimal structural type for the slice of the Bun global we use. Kept local
+ *  so the shim also type-checks without relying on ambient `@types/bun`. */
+interface BunGlobal {
+  file(path: string): { text(): Promise<string> };
+  write(path: string, data: string): Promise<number>;
+  Glob: new (pattern: string) => {
+    scanSync(opts: { cwd: string; onlyFiles: boolean }): Iterable<string>;
+  };
+}
+
+const BUN: BunGlobal | undefined = (globalThis as { Bun?: BunGlobal }).Bun;
+
+/** Which runtime is executing: `'bun'` (primary) or `'node'` (fallback). */
+export const RUNTIME: 'bun' | 'node' = BUN ? 'bun' : 'node';
+
+/** CLI arguments, portable across runtimes (`Bun.argv` is an alias of
+ *  `process.argv`, so the Node form works on both). */
+export function argv(): string[] {
+  return process.argv.slice(2);
+}
+
+/** Directory of the module file that passed its `import.meta.url` — the
+ *  portable replacement for Bun's `import.meta.dir` (Node has no equivalent
+ *  property; both runtimes support `node:url.fileURLToPath`). */
+export function dirFromUrl(moduleUrl: string): string {
+  return dirname(fileURLToPath(moduleUrl));
+}
+
+/** Read a UTF-8 text file. Bun: `Bun.file(path).text()` (unchanged fast path).
+ *  Node: `fs/promises.readFile`. Rejects on missing files on both runtimes. */
+export async function readText(path: string): Promise<string> {
+  if (BUN) return BUN.file(path).text();
+  return readFile(path, 'utf8');
+}
+
+/** Write a UTF-8 text file, creating missing parent directories — `Bun.write`
+ *  auto-creates parents, so the Node path replicates that (plain
+ *  `writeFile` would not) to keep behavior identical across runtimes. */
+export async function writeText(path: string, data: string): Promise<void> {
+  if (BUN) {
+    await BUN.write(path, data);
+    return;
+  }
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, data, 'utf8');
+}
+
+function isDir(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** Glob relative file paths under `dir`, sorted lexicographically — portable
+ *  replacement for `new Bun.Glob(pattern).scanSync({ cwd, onlyFiles: true })`.
+ *  Supported forms: single-segment (`*.md`) and recursive (a two-star prefix
+ *  followed by a slash, e.g. "**" + "/" + "*.md") wildcard patterns; `*` never
+ *  crosses `/` (same as Bun.Glob). Returns paths relative to `dir`, sorted.
+ *  Empty array when `dir` does not exist (unchanged contract used by
+ *  `_tasks`/`_adr` discovery). */
+export function globFiles(dir: string, pattern: string): string[] {
+  if (!isDir(dir)) return [];
+  if (BUN) {
+    const g = new BUN.Glob(pattern);
+    return [...g.scanSync({ cwd: dir, onlyFiles: true }) as Iterable<string>].sort();
+  }
+  const recursive = pattern.startsWith('**/');
+  const base = recursive ? pattern.slice(3) : pattern;
+  const re = new RegExp(
+    `^(?:${base.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '[^/]*')})$`,
+  );
+  const out: string[] = [];
+  if (recursive) {
+    const walk = (d: string, prefix: string): void => {
+      let entries;
+      try {
+        entries = readdirSync(d, { withFileTypes: true });
+      } catch {
+        return;
+      }
+      for (const e of entries) {
+        const rel = prefix === '' ? e.name : `${prefix}/${e.name}`;
+        if (e.isFile() && re.test(e.name)) out.push(rel);
+        else if (e.isDirectory()) walk(join(d, e.name), rel);
+      }
+    };
+    walk(dir, '');
+  } else {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.isFile() && re.test(e.name)) out.push(e.name);
+    }
+  }
+  return out.sort();
+}

package/src/core/structure.ts

@@ -1,5 +1,5 @@
-import type { OutlineNode, Issue, StructureRules, ContentRules } from '../types';
-import { flattenNodes } from './outline';
+import type { OutlineNode, Issue, StructureRules, ContentRules } from '../types.ts';
+import { flattenNodes } from './outline.ts';
 
 /** Structure checks: node length, depth, sibling count, single-child collapse, empty nodes.
  *  §18 delete-key semantics: a check whose rules key is null/false is OFF — the

package/src/core/style.ts

@@ -1,4 +1,4 @@
-import type { OutlineNode, Issue, StyleRules } from '../types';
+import type { OutlineNode, Issue, StyleRules } from '../types.ts';
 
 /** Style checks: shared-prefix nesting hint + unnecessary-nesting collapse hint.
  *  SEVERITY NOTE (arbitration, same class as the refs-severity decision): §14/§36

package/src/core/token-budget.ts

@@ -3,9 +3,9 @@ import { basename, relative } from 'path';
 import type {
   OutlineNode, BackPointer, TokenBudgetRules,
   BudgetReadPlanItem, BudgetReadResult, BudgetWriteResult,
-} from '../types';
-import { flattenNodes, parseOutline } from './outline';
-import { targetMatchesKey } from './refs';
+} from '../types.ts';
+import { flattenNodes, parseOutline } from './outline.ts';
+import { targetMatchesKey } from './refs.ts';
 
 export function estimateTokens(text: string, charsPerToken: number): number {
   return Math.ceil(text.length / charsPerToken);