agency-lang 0.0.98 → 0.0.100

package/dist/lib/backends/typescriptBuilder.js

@@ -1,3 +1,4 @@
+import path from "path";
 import { formatTypeHint } from "../cli/util.js";
 import { BUILTIN_FUNCTIONS, BUILTIN_TOOLS, BUILTIN_VARIABLES, TYPES_THAT_DONT_TRIGGER_NEW_PART, } from "../config.js";
 import { expressionToString } from "../utils/node.js";
@@ -1041,7 +1042,7 @@ export class TypeScriptBuilder {
         return ts.runnerIfElse({ id, branches, elseBranch });
     }
     processImportStatement(node) {
-        const from = toCompiledImportPath(node.modulePath);
+        const from = toCompiledImportPath(node.modulePath, path.resolve(this.moduleId));
         const imports = node.importedNames.map((nameType) => {
             switch (nameType.type) {
                 case "namedImport":
@@ -1092,7 +1093,7 @@ export class TypeScriptBuilder {
         return ts.importDecl({
             importKind: "named",
             names: importNames,
-            from: toCompiledImportPath(node.agencyFile),
+            from: toCompiledImportPath(node.agencyFile, path.resolve(this.moduleId)),
         });
     }
     // ------- TsRaw wrapper methods (template-heavy) -------

package/dist/lib/cli/commands.d.ts

@@ -1,6 +1,7 @@
 import { AgencyConfig } from "../config.js";
 import { AgencyProgram } from "../index.js";
 import { type SymbolTable } from "../symbolTable.js";
+import { type ImportStrategy } from "../importStrategy.js";
 export declare function loadConfig(configPath?: string, verbose?: boolean): AgencyConfig;
 export declare function readStdin(): Promise<string>;
 export declare function parse(contents: string, config: AgencyConfig, applyTemplate?: boolean): AgencyProgram;
@@ -9,6 +10,7 @@ export declare function resetCompilationCache(): void;
 export declare function compile(config: AgencyConfig, inputFile: string, _outputFile?: string, options?: {
     ts?: boolean;
     symbolTable?: SymbolTable;
+    importStrategy?: ImportStrategy;
 }): string | null;
 export declare function run(config: AgencyConfig, inputFile: string, outputFile?: string, resumeFile?: string): void;
 export declare function format(contents: string, config: AgencyConfig): Promise<string>;

package/dist/lib/cli/commands.js

@@ -8,7 +8,8 @@ import { spawn } from "child_process";
 import { transformSync } from "esbuild";
 import * as fs from "fs";
 import * as path from "path";
-import { getStdlibDir, isPkgImport, isStdlibImport, resolveAgencyImportPath, resolveFlexibleExtension, } from "../importPaths.js";
+import { getStdlibDir, isPkgImport, isStdlibImport, resolveAgencyImportPath, } from "../importPaths.js";
+import { CompileStrategy, RunStrategy } from "../importStrategy.js";
 import { parseAgency } from "../parser.js";
 import { findRecursively, getImports } from "./util.js";
 // Load configuration from agency.json
@@ -126,8 +127,11 @@ export function compile(config, inputFile, _outputFile, options) {
     }
     const imports = getImports(resolvedProgram);
     for (const importPath of imports) {
+        // stdlib and pkg imports are pre-compiled; don't recompile them
+        if (isStdlibImport(importPath) || isPkgImport(importPath))
+            continue;
         const absPath = resolveAgencyImportPath(importPath, absoluteInputFile);
-        if (config.restrictImports && !isStdlibImport(importPath) && !isPkgImport(importPath)) {
+        if (config.restrictImports) {
             const projectRoot = process.cwd();
             if (!absPath.startsWith(projectRoot + path.sep) &&
                 absPath !== projectRoot) {
@@ -136,33 +140,21 @@ export function compile(config, inputFile, _outputFile, options) {
         }
         compile(config, absPath, undefined, { ...options, symbolTable });
     }
-    // Update import paths in the AST
+    // Rewrite import paths in the AST using the import strategy
+    const strategy = options?.importStrategy ?? new CompileStrategy({ targetExt: ext });
+    const nonAgencyImports = [];
     resolvedProgram.nodes.forEach((node) => {
         if (node.type !== "importStatement")
             return;
         if (isStdlibImport(node.modulePath) || isPkgImport(node.modulePath))
             return;
-        if (node.modulePath.endsWith(".agency")) {
-            node.modulePath = node.modulePath.replace(".agency", ext);
-            return;
-        }
-        // For .js/.ts imports, resolve flexibly: if the specified file doesn't
-        // exist, try the other extension. This lets users write .js imports that
-        // work in dist/ while the debugger finds the .ts source (and vice versa).
-        if (node.modulePath.endsWith(".js") || node.modulePath.endsWith(".ts")) {
-            const resolved = resolveFlexibleExtension(node.modulePath, absoluteInputFile);
-            if (resolved === null) {
-                const altExt = node.modulePath.endsWith(".js") ? ".ts" : ".js";
-                const altPath = node.modulePath.replace(/\.(js|ts)$/, altExt);
-                console.error(`Error: Cannot resolve import '${node.modulePath}' from '${inputFile}'.\n` +
-                    `Tried: ${node.modulePath}, ${altPath} — neither file exists.`);
-                process.exit(1);
-            }
-            // Rewrite the import to use whatever extension actually exists on disk
-            const resolvedExt = path.extname(resolved);
-            node.modulePath = node.modulePath.replace(/\.(js|ts)$/, resolvedExt);
+        node.modulePath = strategy.rewriteImport(node.modulePath, absoluteInputFile);
+        // Collect non-Agency imports for dependency preparation
+        if (!node.modulePath.endsWith(".agency")) {
+            nonAgencyImports.push(node.modulePath);
         }
     });
+    strategy.prepareDependencies(nonAgencyImports, absoluteInputFile);
     const moduleId = path.relative(process.cwd(), absoluteInputFile);
     const generatedCode = generateTypeScript(resolvedProgram, config, info, moduleId);
     if (options?.ts) {
@@ -182,8 +174,8 @@ export function compile(config, inputFile, _outputFile, options) {
     return outputFile;
 }
 export function run(config, inputFile, outputFile, resumeFile) {
-    // Compile the file
-    const output = compile(config, inputFile, outputFile);
+    // Compile the file with RunStrategy so dependencies are prepared for execution
+    const output = compile(config, inputFile, outputFile, { importStrategy: new RunStrategy() });
     if (output === null) {
         console.error("Error: No output file generated.");
         process.exit(1);

package/dist/lib/cli/debug.js

@@ -1,5 +1,6 @@
 import { compile } from "./commands.js";
-import { pickANode } from "./util.js";
+import { RunStrategy } from "../importStrategy.js";
+import { pickANode, resolveCompiledFile } from "./util.js";
 import { parseAgency } from "../parser.js";
 import { getNodesOfType } from "../utils/node.js";
 import { DebuggerDriver } from "../debugger/driver.js";
@@ -82,13 +83,7 @@ export async function debug(config, _inputFile, options = {}) {
         let absOutput;
         if (distDir) {
             // distDir mode: import pre-compiled JS from the dist directory
-            const basename = path.basename(inputFile, ".agency") + ".js";
-            const compiledPath = path.resolve(distDir, basename);
-            if (!fs.existsSync(compiledPath)) {
-                console.error(`Error: Compiled file not found: ${compiledPath}\n` +
-                    `Make sure you have compiled your Agency files and that distDir is correct.`);
-                process.exit(1);
-            }
+            const compiledPath = resolveCompiledFile(distDir, inputFile);
             // Warn if source is newer than compiled output
             const sourceMtime = fs.statSync(inputFile).mtimeMs;
             const compiledMtime = fs.statSync(compiledPath).mtimeMs;
@@ -101,7 +96,7 @@ export async function debug(config, _inputFile, options = {}) {
         else {
             // Normal mode: compile the .agency file to .js on the fly
             const debugConfig = { ...config, debugger: true };
-            const outputFile = compile(debugConfig, inputFile);
+            const outputFile = compile(debugConfig, inputFile, undefined, { importStrategy: new RunStrategy() });
             if (outputFile === null) {
                 console.error("Error: No output file generated.");
                 process.exit(1);

package/dist/lib/cli/util.d.ts

@@ -21,6 +21,11 @@ export type InterruptHandler = {
     resolvedValue?: any;
     expectedMessage?: string;
 };
+/**
+ * Resolve the compiled .js file for an .agency file from a distDir.
+ * Throws if the compiled file doesn't exist.
+ */
+export declare function resolveCompiledFile(distDir: string, agencyFile: string): string;
 type ExecuteNodeArgs = {
     config: AgencyConfig;
     agencyFile: string;

package/dist/lib/cli/util.js

@@ -11,6 +11,7 @@ import { isAgencyImport, resolveAgencyImportPath, getStdlibDir } from "../import
 import renderEvaluate from "../templates/cli/evaluate.js";
 import renderJudgeEvaluate from "../templates/cli/judgeEvaluate.js";
 import { compile } from "./commands.js";
+import { RunStrategy } from "../importStrategy.js";
 import { parseAgency } from "../parser.js";
 export function parseTarget(target) {
     const colonIndex = target.lastIndexOf(":");
@@ -103,28 +104,39 @@ export async function promptForArgs(selectedNode) {
     }
     return { hasArgs, argsString };
 }
+/**
+ * Resolve the compiled .js file for an .agency file from a distDir.
+ * Throws if the compiled file doesn't exist.
+ */
+export function resolveCompiledFile(distDir, agencyFile) {
+    const basename = path.basename(agencyFile, ".agency") + ".js";
+    const compiledPath = path.resolve(distDir, basename);
+    if (!fs.existsSync(compiledPath)) {
+        throw new Error(`Compiled file not found: ${compiledPath}\n` +
+            `Make sure you have compiled your Agency files and that distDir is correct.`);
+    }
+    return compiledPath;
+}
 export async function executeNodeAsync({ config, agencyFile, nodeName, hasArgs, argsString, interruptHandlers, }) {
     const distDir = config.distDir;
-    let compiledFilename;
+    let compiledPath;
     if (distDir) {
-        // distDir mode: skip compilation, import pre-compiled JS from distDir
-        const basename = path.basename(agencyFile, ".agency") + ".js";
-        const compiledPath = path.resolve(distDir, basename);
-        if (!fs.existsSync(compiledPath)) {
-            throw new Error(`Compiled file not found: ${compiledPath}\n` +
-                `Make sure you have compiled your Agency files and that distDir is correct.`);
-        }
-        compiledFilename = compiledPath;
+        compiledPath = resolveCompiledFile(distDir, agencyFile);
     }
     else {
-        compile(config, agencyFile);
-        compiledFilename = path.basename(agencyFile).replace(".agency", ".js");
+        compiledPath = compile(config, agencyFile, undefined, { importStrategy: new RunStrategy() });
     }
     const baseName = agencyFile.replace(".agency", "");
     const evaluateFile = `${baseName}.evaluate.js`;
     const resultsFile = `${baseName}.evaluate.json`;
+    // The template imports via "./${filename}", so compute a relative path
+    // from the evaluate script's directory to the compiled module.
+    let importSpecifier = path.relative(path.dirname(evaluateFile), compiledPath).replace(/\\/g, "/");
+    if (!importSpecifier.startsWith(".")) {
+        importSpecifier = `./${importSpecifier}`;
+    }
     const evaluateScript = renderEvaluate({
-        filename: compiledFilename,
+        filename: importSpecifier,
         nodeName,
         hasArgs,
         args: argsString,
@@ -153,22 +165,22 @@ export async function executeNodeAsync({ config, agencyFile, nodeName, hasArgs,
 }
 export function executeNode(args) {
     const distDir = args.config.distDir;
-    let compiledFilename;
+    let compiledPath;
     if (distDir) {
-        const basename = path.basename(args.agencyFile, ".agency") + ".js";
-        const compiledPath = path.resolve(distDir, basename);
-        if (!fs.existsSync(compiledPath)) {
-            throw new Error(`Compiled file not found: ${compiledPath}\n` +
-                `Make sure you have compiled your Agency files and that distDir is correct.`);
-        }
-        compiledFilename = compiledPath;
+        compiledPath = resolveCompiledFile(distDir, args.agencyFile);
     }
     else {
-        compile(args.config, args.agencyFile);
-        compiledFilename = args.agencyFile.replace(".agency", ".js");
+        compiledPath = compile(args.config, args.agencyFile, undefined, { importStrategy: new RunStrategy() });
+    }
+    const evaluateFile = "__evaluate.js";
+    // The template imports via "./${filename}", so compute a relative path
+    // from the evaluate script's directory to the compiled module.
+    let importSpecifier = path.relative(path.dirname(evaluateFile), compiledPath).replace(/\\/g, "/");
+    if (!importSpecifier.startsWith(".")) {
+        importSpecifier = `./${importSpecifier}`;
     }
     const evaluateScript = renderEvaluate({
-        filename: compiledFilename,
+        filename: importSpecifier,
         nodeName: args.nodeName,
         hasArgs: args.hasArgs,
         args: args.argsString,
@@ -178,7 +190,6 @@ export function executeNode(args) {
             : undefined,
         resultsFilename: "__evaluate.json",
     });
-    const evaluateFile = "__evaluate.js";
     fs.writeFileSync(evaluateFile, evaluateScript);
     execFileSync("node", [evaluateFile], { stdio: "inherit" });
     const results = readFileSync("__evaluate.json", "utf-8");

package/dist/lib/debugger/ui.js

@@ -395,7 +395,7 @@ export class DebuggerUI {
     renderSourcePane() {
         const moduleId = this.state.getModuleId();
         const currentLine = this.state.getCurrentLine();
-        const filePath = moduleId;
+        const filePath = this.state.resolveModulePath(moduleId, [".agency"]) ?? moduleId;
         const fileContent = readSourceFile(filePath);
         const highlighted = syntaxHighlight(fileContent, "ts");
         const lines = highlighted.split("\n");

package/dist/lib/debugger/uiState.d.ts

@@ -19,6 +19,12 @@ export declare class UIState {
     private sourceMapCache;
     constructor();
     static fromCheckpoint(checkpoint: Checkpoint | undefined): UIState;
+    /**
+     * Resolve a moduleId (e.g., "stdlib/index.agency") to an actual file path,
+     * trying the given extensions. Handles stdlib modules that live inside
+     * node_modules/agency-lang/stdlib/ when running from an external project.
+     */
+    resolveModulePath(moduleId: string, extensions: string[]): string | null;
     private agencyToJsFile;
     setCheckpoint(checkpoint: Checkpoint | undefined): Promise<void>;
     setWithOverrides(obj: Record<string, unknown>, array: ValWithOverride[]): void;

package/dist/lib/debugger/uiState.js

@@ -1,5 +1,6 @@
 import { Checkpoint } from "../runtime/state/checkpointStore.js";
 import { GlobalStore } from "../runtime/state/globalStore.js";
+import { getStdlibDir } from "../importPaths.js";
 import fs from "fs";
 import path from "path";
 export class UIState {
@@ -30,17 +31,34 @@ export class UIState {
         uiState.setCheckpoint(checkpoint);
         return uiState;
     }
-    agencyToJsFile(agencyFile) {
-        const tsFile = agencyFile.replace(/\.agency$/, ".ts");
-        if (fs.existsSync(tsFile)) {
-            return tsFile;
+    /**
+     * Resolve a moduleId (e.g., "stdlib/index.agency") to an actual file path,
+     * trying the given extensions. Handles stdlib modules that live inside
+     * node_modules/agency-lang/stdlib/ when running from an external project.
+     */
+    resolveModulePath(moduleId, extensions) {
+        // Try the path as-is first (works when running from the agency-lang repo)
+        for (const ext of extensions) {
+            const candidate = moduleId.replace(/\.agency$/, ext);
+            if (fs.existsSync(candidate))
+                return candidate;
         }
-        const jsFile = agencyFile.replace(/\.agency$/, ".js");
-        if (fs.existsSync(jsFile)) {
-            return jsFile;
+        // If the moduleId refers to a stdlib file, resolve against the actual
+        // stdlib directory (handles npm-installed packages where stdlib lives
+        // in node_modules/agency-lang/stdlib/)
+        if (moduleId.includes("stdlib")) {
+            const basename = path.basename(moduleId);
+            for (const ext of extensions) {
+                const candidate = path.join(getStdlibDir(), basename).replace(/\.agency$/, ext);
+                if (fs.existsSync(candidate))
+                    return candidate;
+            }
         }
         return null;
     }
+    agencyToJsFile(agencyFile) {
+        return this.resolveModulePath(agencyFile, [".js", ".ts"]);
+    }
     async setCheckpoint(checkpoint) {
         const cp = Checkpoint.fromJSON(checkpoint);
         if (!cp) {

package/dist/lib/importPaths.d.ts

@@ -64,17 +64,15 @@ export declare function resolvePkgAgencyPath(importPath: string, fromFile: strin
  * - "./foo.js"       -> resolved relative to the importing file (non-agency, kept as-is)
  */
 export declare function resolveAgencyImportPath(importPath: string, fromFile: string): string;
-/**
- * Resolve a .js or .ts import path, trying the other extension if the
- * specified file doesn't exist. Returns the resolved absolute path, or
- * null if neither extension exists on disk.
- */
-export declare function resolveFlexibleExtension(importPath: string, fromFile: string): string | null;
 /**
  * Convert an Agency import path to the path that should appear in generated
  * TypeScript import statements.
  *
- * - "std::foo"      -> absolute path to <stdlib-dir>/foo.js
+ * - "std::foo"      -> relative path to <stdlib-dir>/foo.js from the source file
  * - "./foo.agency"  -> "./foo.js" (relative, just extension swap)
+ *
+ * @param fromFile - Absolute path of the source file containing the import.
+ *   Used to compute relative paths for stdlib imports. If not provided,
+ *   falls back to absolute paths.
  */
-export declare function toCompiledImportPath(importPath: string): string;
+export declare function toCompiledImportPath(importPath: string, fromFile?: string): string;

package/dist/lib/importPaths.js

@@ -216,39 +216,27 @@ export function resolveAgencyImportPath(importPath, fromFile) {
     // Relative or other imports: resolve against the importing file's directory
     return path.resolve(path.dirname(fromFile), importPath);
 }
-const FLEXIBLE_EXTENSIONS = {
-    ".js": ".ts",
-    ".ts": ".js",
-};
-/**
- * Resolve a .js or .ts import path, trying the other extension if the
- * specified file doesn't exist. Returns the resolved absolute path, or
- * null if neither extension exists on disk.
- */
-export function resolveFlexibleExtension(importPath, fromFile) {
-    const ext = path.extname(importPath);
-    const altExt = FLEXIBLE_EXTENSIONS[ext];
-    if (!altExt)
-        return null; // not a .js/.ts import
-    const dir = path.dirname(fromFile);
-    const resolved = path.resolve(dir, importPath);
-    if (fs.existsSync(resolved))
-        return resolved;
-    const altPath = resolved.slice(0, -ext.length) + altExt;
-    if (fs.existsSync(altPath))
-        return altPath;
-    return null;
-}
 /**
  * Convert an Agency import path to the path that should appear in generated
  * TypeScript import statements.
  *
- * - "std::foo"      -> absolute path to <stdlib-dir>/foo.js
+ * - "std::foo"      -> relative path to <stdlib-dir>/foo.js from the source file
  * - "./foo.agency"  -> "./foo.js" (relative, just extension swap)
+ *
+ * @param fromFile - Absolute path of the source file containing the import.
+ *   Used to compute relative paths for stdlib imports. If not provided,
+ *   falls back to absolute paths.
  */
-export function toCompiledImportPath(importPath) {
+export function toCompiledImportPath(importPath, fromFile) {
     if (isStdlibImport(importPath)) {
-        return path.join(STDLIB_DIR, normalizeStdlibPath(importPath) + ".js");
+        const absTarget = path.join(STDLIB_DIR, normalizeStdlibPath(importPath) + ".js");
+        if (fromFile) {
+            let rel = path.relative(path.dirname(fromFile), absTarget).replace(/\\/g, "/");
+            if (!rel.startsWith("."))
+                rel = "./" + rel;
+            return rel;
+        }
+        return absTarget;
     }
     if (isPkgImport(importPath)) {
         // Emit bare specifier — Node resolves it at runtime via node_modules

package/dist/lib/importPaths.test.js

@@ -1,5 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
-import { findPackageRoot, resolveAgencyImportPath, resolveFlexibleExtension, getStdlibDir, toCompiledImportPath, isPkgImport, isAgencyImport, parsePkgImport, resolvePkgAgencyPath, } from "./importPaths.js";
+import { findPackageRoot, resolveAgencyImportPath, getStdlibDir, toCompiledImportPath, isPkgImport, isAgencyImport, parsePkgImport, resolvePkgAgencyPath, } from "./importPaths.js";
+import { CompileStrategy, RunStrategy } from "./importStrategy.js";
 import { buildSymbolTable } from "./symbolTable.js";
 import * as fs from "fs";
 import * as os from "os";
@@ -235,52 +236,73 @@ describe("buildSymbolTable with pkg:: imports", () => {
         }
     });
 });
-describe("resolveFlexibleExtension", () => {
+describe("CompileStrategy", () => {
+    const jsStrategy = new CompileStrategy({ targetExt: ".js" });
+    const tsStrategy = new CompileStrategy({ targetExt: ".ts" });
+    it("should rewrite .agency to .js", () => {
+        expect(jsStrategy.rewriteImport("./foo.agency", "/src/main.agency")).toBe("./foo.js");
+    });
+    it("should rewrite .agency to .ts with --ts", () => {
+        expect(tsStrategy.rewriteImport("./foo.agency", "/src/main.agency")).toBe("./foo.ts");
+    });
+    it("should leave .js imports untouched", () => {
+        expect(jsStrategy.rewriteImport("./tools.js", "/src/main.agency")).toBe("./tools.js");
+    });
+    it("should leave .ts imports untouched", () => {
+        expect(jsStrategy.rewriteImport("./tools.ts", "/src/main.agency")).toBe("./tools.ts");
+    });
+    it("should leave bare specifiers untouched", () => {
+        expect(jsStrategy.rewriteImport("nanoid", "/src/main.agency")).toBe("nanoid");
+    });
+});
+describe("RunStrategy", () => {
+    const strategy = new RunStrategy();
+    it("should rewrite .agency to .js", () => {
+        expect(strategy.rewriteImport("./foo.agency", "/src/main.agency")).toBe("./foo.js");
+    });
+    it("should rewrite .ts to .js", () => {
+        expect(strategy.rewriteImport("./tools.ts", "/src/main.agency")).toBe("./tools.js");
+    });
+    it("should leave .js imports as-is", () => {
+        expect(strategy.rewriteImport("./tools.js", "/src/main.agency")).toBe("./tools.js");
+    });
+    it("should leave bare specifiers untouched", () => {
+        expect(strategy.rewriteImport("nanoid", "/src/main.agency")).toBe("nanoid");
+    });
+});
+describe("RunStrategy.prepareDependencies", () => {
     let tmpDir;
+    const strategy = new RunStrategy();
     beforeEach(() => {
-        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agency-flex-ext-"));
+        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "agency-run-strategy-"));
     });
     afterEach(() => {
         fs.rmSync(tmpDir, { recursive: true, force: true });
     });
-    it("should return the resolved path when the file exists as-is", () => {
+    it("should compile .ts to .js when .js doesn't exist", () => {
         const tsFile = path.join(tmpDir, "bar.ts");
-        fs.writeFileSync(tsFile, "export const x = 1;");
-        const fromFile = path.join(tmpDir, "main.agency");
-        const result = resolveFlexibleExtension("./bar.ts", fromFile);
-        expect(result).toBe(tsFile);
-    });
-    it("should fall back from .js to .ts when .js doesn't exist", () => {
-        const tsFile = path.join(tmpDir, "bar.ts");
-        fs.writeFileSync(tsFile, "export const x = 1;");
-        const fromFile = path.join(tmpDir, "main.agency");
-        const result = resolveFlexibleExtension("./bar.js", fromFile);
-        expect(result).toBe(tsFile);
-    });
-    it("should fall back from .ts to .js when .ts doesn't exist", () => {
         const jsFile = path.join(tmpDir, "bar.js");
-        fs.writeFileSync(jsFile, "export const x = 1;");
+        fs.writeFileSync(tsFile, "export const x: number = 1;");
         const fromFile = path.join(tmpDir, "main.agency");
-        const result = resolveFlexibleExtension("./bar.ts", fromFile);
-        expect(result).toBe(jsFile);
+        strategy.prepareDependencies(["./bar.js"], fromFile);
+        expect(fs.existsSync(jsFile)).toBe(true);
+        const content = fs.readFileSync(jsFile, "utf-8");
+        expect(content).toContain("const x = 1");
     });
-    it("should return null when neither .js nor .ts exists", () => {
+    it("should not overwrite existing .js files", () => {
+        const jsFile = path.join(tmpDir, "bar.js");
+        fs.writeFileSync(jsFile, "// original");
         const fromFile = path.join(tmpDir, "main.agency");
-        const result = resolveFlexibleExtension("./bar.js", fromFile);
-        expect(result).toBeNull();
+        strategy.prepareDependencies(["./bar.js"], fromFile);
+        expect(fs.readFileSync(jsFile, "utf-8")).toBe("// original");
     });
-    it("should return null for non-.js/.ts extensions", () => {
+    it("should throw when neither .js nor .ts exists", () => {
         const fromFile = path.join(tmpDir, "main.agency");
-        const result = resolveFlexibleExtension("./bar.css", fromFile);
-        expect(result).toBeNull();
+        expect(() => strategy.prepareDependencies(["./bar.js"], fromFile)).toThrow(/Cannot resolve import/);
     });
-    it("should prefer the exact extension when both files exist", () => {
-        const jsFile = path.join(tmpDir, "bar.js");
-        const tsFile = path.join(tmpDir, "bar.ts");
-        fs.writeFileSync(jsFile, "export const x = 1;");
-        fs.writeFileSync(tsFile, "export const x = 1;");
+    it("should skip bare specifiers", () => {
         const fromFile = path.join(tmpDir, "main.agency");
-        expect(resolveFlexibleExtension("./bar.js", fromFile)).toBe(jsFile);
-        expect(resolveFlexibleExtension("./bar.ts", fromFile)).toBe(tsFile);
+        // Should not throw — bare specifiers are skipped
+        strategy.prepareDependencies(["nanoid"], fromFile);
     });
 });

package/dist/lib/importStrategy.d.ts

@@ -0,0 +1,37 @@
+export type CompileOptions = {
+    /** Extension for .agency rewrites: ".js" or ".ts" */
+    targetExt: ".js" | ".ts";
+};
+export interface ImportStrategy {
+    /**
+     * Rewrite an import path for the output.
+     * Handles .agency, .js, and .ts imports.
+     */
+    rewriteImport(modulePath: string, sourceFile: string): string;
+    /**
+     * Ensure all non-Agency dependencies are available for execution.
+     * Called after compilation, before the output is executed.
+     * Errors if a dependency can't be resolved.
+     */
+    prepareDependencies(imports: string[], sourceFile: string): void;
+}
+/**
+ * Strategy for `agency compile`: produces output for a downstream build pipeline.
+ * Leaves .js/.ts imports untouched. Only rewrites .agency imports.
+ */
+export declare class CompileStrategy implements ImportStrategy {
+    protected options: CompileOptions;
+    constructor(options: CompileOptions);
+    rewriteImport(modulePath: string, _sourceFile: string): string;
+    prepareDependencies(_imports: string[], _sourceFile: string): void;
+}
+/**
+ * Strategy for `agency run` / `agency debug` / `agency test`: compiles and
+ * immediately executes. All imports must resolve to .js files that exist on disk.
+ * Compiles .ts dependencies to .js via esbuild when needed.
+ */
+export declare class RunStrategy extends CompileStrategy {
+    constructor();
+    rewriteImport(modulePath: string, sourceFile: string): string;
+    prepareDependencies(imports: string[], sourceFile: string): void;
+}

package/dist/lib/importStrategy.js

@@ -0,0 +1,64 @@
+import * as fs from "fs";
+import * as path from "path";
+import { transformSync } from "esbuild";
+/**
+ * Strategy for `agency compile`: produces output for a downstream build pipeline.
+ * Leaves .js/.ts imports untouched. Only rewrites .agency imports.
+ */
+export class CompileStrategy {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    rewriteImport(modulePath, _sourceFile) {
+        if (modulePath.endsWith(".agency")) {
+            return modulePath.replace(/\.agency$/, this.options.targetExt);
+        }
+        return modulePath;
+    }
+    prepareDependencies(_imports, _sourceFile) {
+        // No-op — user's build pipeline handles dependencies
+    }
+}
+/**
+ * Strategy for `agency run` / `agency debug` / `agency test`: compiles and
+ * immediately executes. All imports must resolve to .js files that exist on disk.
+ * Compiles .ts dependencies to .js via esbuild when needed.
+ */
+export class RunStrategy extends CompileStrategy {
+    constructor() {
+        super({ targetExt: ".js" });
+    }
+    rewriteImport(modulePath, sourceFile) {
+        if (modulePath.endsWith(".agency")) {
+            return super.rewriteImport(modulePath, sourceFile);
+        }
+        // Always produce .js — Node needs .js at runtime
+        return modulePath.replace(/\.ts$/, ".js");
+    }
+    prepareDependencies(imports, sourceFile) {
+        for (const imp of imports) {
+            if (!imp.startsWith("./") && !imp.startsWith("../"))
+                continue;
+            if (!imp.endsWith(".js"))
+                continue;
+            const resolved = path.resolve(path.dirname(sourceFile), imp);
+            if (fs.existsSync(resolved))
+                continue;
+            const tsPath = resolved.replace(/\.js$/, ".ts");
+            if (fs.existsSync(tsPath)) {
+                const tsCode = fs.readFileSync(tsPath, "utf-8");
+                const result = transformSync(tsCode, {
+                    loader: "ts",
+                    format: "esm",
+                    supported: { "top-level-await": true },
+                });
+                fs.writeFileSync(resolved, result.code);
+            }
+            else {
+                throw new Error(`Cannot resolve import '${imp}' from '${sourceFile}'.\n` +
+                    `Tried: ${resolved}, ${tsPath} — neither file exists.`);
+            }
+        }
+    }
+}

package/dist/lib/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.0.98";
+export declare const VERSION = "0.0.100";

package/dist/lib/version.js

@@ -1 +1 @@
-export const VERSION = "0.0.98";
+export const VERSION = "0.0.100";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agency-lang",
-  "version": "0.0.98",
+  "version": "0.0.100",
   "description": "The Agency language",
   "main": "lib/index.js",
   "scripts": {