cans-spec 0.1.2 → 0.3.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.2",
+  "version": "0.3.0",
   "description": "Canonical Agent-Native Spec — 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,24 +1,28 @@
-#!/usr/bin/env bun
+#!/usr/bin/env node
 
-import type { CommandResult } from './types';
-import { emit } from './core/output';
-import pkg from '../package.json';
+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 — derived from package.json so it can never drift. */
-const VERSION: string = pkg.version;
+/** §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,
+  parseOutline, extractBackPointers, realNodes, 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;
@@ -41,6 +42,10 @@ const CHECK_FLAGS: FlagSpec[] = [
 ];
 
 const REF_BY_RE = /<!--\s*ref-by:\s*(.*?)\s*-->/;
+// Fence marker rule, mirrored from src/core/outline.ts (issue #6): a line whose
+// trimmed form starts with ``` toggles fence state. Kept as a regex to reuse
+// the outline.ts FENCE_RE convention; the two must never diverge.
+const FENCE_RE = /^```/;
 
 // globFiles throws ENOENT on missing dirs — guard the optional ones.
 function safeActiveTasks(root: string): string[] {
@@ -110,15 +115,56 @@ function refTargetKey(name: string, keys: Iterable<string>): string | null {
   return null;
 }
 
+/** Issue #6: remove ONLY the ref-by comment substring from a non-bullet line,
+ *  keeping the surrounding prose. Collapses the double space left where the
+ *  comment sat (one seam space absorbed) and trims trailing whitespace. The
+ *  caller drops the line only when nothing but the comment remains. */
+function stripRefByKeepProse(raw: string): string {
+  const m = raw.match(REF_BY_RE);
+  if (m === null || m.index === undefined) return raw;
+  let out = raw.slice(0, m.index) + raw.slice(m.index + m[0].length);
+  if (out.charAt(m.index - 1) === ' ' && out.charAt(m.index) === ' ') {
+    out = out.slice(0, m.index - 1) + out.slice(m.index);
+  }
+  return out.replace(/[ \t]+$/, '');
+}
+
 /** Rewrite `<!-- ref-by: ... -->` comments in one spec file source.
- *  Replaces the first existing comment's content, drops duplicates/stale ones,
- *  or inserts a fresh comment line right after the first root bullet. */
-function rewriteRefBy(source: string, body: string | null): string {
+ *  Fence-aware and prose-preserving (issue #6):
+ *  - Lines inside ``` fences (and the fence markers themselves) are preserved
+ *    byte-for-byte: never scanned as hits, never rewritten, never dropped, and
+ *    fenced "- fake bullets" are never insertion anchors.
+ *  - Replaces the first existing comment's content; duplicates/stale hits keep
+ *    their line — bullets are stripped as before, non-bullet prose loses only
+ *    the comment substring (the line is dropped only when bare).
+ *  - With no hits and a desired body, inserts a fresh comment line right after
+ *    the first root bullet outside any fence, appended at end when none exists
+ *    — unless the file ends inside an unterminated fence, in which case the
+ *    comment is inserted before the fence opener (never inside a fence).
+ *  Exported for regression tests (issue #6); behavior lives in this module. */
+export function rewriteRefBy(source: string, body: string | null): string {
   const lines: Array<string | null> = source.split('\n');
   const comment = body !== null && body !== '' ? `<!-- ref-by: ${body} -->` : null;
   const hits: number[] = [];
+  let fenceOpen = false;
+  let fenceOpener = -1;
+  const inFence: boolean[] = new Array(lines.length).fill(false);
   for (let i = 0; i < lines.length; i++) {
-    if (lines[i] !== null && REF_BY_RE.test(lines[i]!)) hits.push(i);
+    const raw = lines[i]!;
+    if (FENCE_RE.test(raw.trim())) {
+      // Fence marker: toggles state; never a hit, never an anchor, never touched.
+      inFence[i] = true;
+      if (fenceOpen) {
+        fenceOpen = false;
+      } else {
+        fenceOpen = true;
+        fenceOpener = i;
+      }
+      continue;
+    }
+    inFence[i] = fenceOpen;
+    if (fenceOpen) continue;
+    if (REF_BY_RE.test(raw)) hits.push(i);
   }
   if (hits.length > 0) {
     for (let j = 0; j < hits.length; j++) {
@@ -128,17 +174,27 @@ function rewriteRefBy(source: string, body: string | null): string {
         lines[i] = raw.replace(REF_BY_RE, comment);
       } else {
         const isBullet = /^\s*-\s/.test(raw);
-        lines[i] = isBullet ? raw.replace(REF_BY_RE, '').replace(/[ \t]+$/, '') : null;
+        if (isBullet) {
+          lines[i] = raw.replace(REF_BY_RE, '').replace(/[ \t]+$/, '');
+        } else {
+          // Issue #6: never delete a prose line whole — strip the comment only.
+          const stripped = stripRefByKeepProse(raw);
+          lines[i] = stripped.trim() === '' ? null : stripped;
+        }
       }
     }
   } else if (comment !== null) {
     let insertAt = lines.length;
     for (let i = 0; i < lines.length; i++) {
+      if (inFence[i]) continue; // fenced `- fake bullets` are not anchors
       if (/^- /.test(lines[i]!)) {
         insertAt = i + 1;
         break;
       }
     }
+    // Issue #6: never insert inside an open fence — appending at EOF while a
+    // fence is unterminated would corrupt the fenced region.
+    if (insertAt >= lines.length && fenceOpen) insertAt = fenceOpener;
     lines.splice(insertAt, 0, comment);
   }
   return lines.filter((l): l is string => l !== null).join('\n');
@@ -181,7 +237,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 +268,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 +364,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 +382,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++;
       }
@@ -363,7 +419,13 @@ export async function checkWorkspace(root: string, opts: CheckArgs): Promise<Che
   let nodeCount = 0;
   let depthMax = 0;
   for (const nodes of specFiles.values()) {
-    nodeCount += flattenNodes(nodes).length;
+    // Issue #8: report REAL nodes only — synthetic "(table)"/"(code fence)"
+    // placeholders (leading table/fence before the first bullet) are not
+    // user content and inflated the header count and budget estimates.
+    nodeCount += realNodes(nodes).length;
+    // Depth keeps the full tree: a synthetic root sits at indent 0, so it can
+    // never raise depthMax; a workspace containing only phantoms now has
+    // nodeCount 0 and correctly reports maxDepth 0 (§35 empty-workspace case).
     depthMax = Math.max(depthMax, outlineMaxDepth(nodes));
   }
   const refsTotal = [...graph.forward.values()].reduce((a, ts) => a + ts.length, 0);

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);
   }