nlang-cli 0.1.0

package/README.md

@@ -0,0 +1,219 @@
+# nlang — Executable Extensions
+
+A build system where **file extensions define the build pipeline**. Files with double extensions (`.html.md`, `.json.js`, `.css.md`) are automatically executed: markdown files are sent to an LLM, JavaScript/TypeScript files are run in Node.js.
+
+## Install
+
+```bash
+npm install -g nlang
+```
+
+## Quick Start
+
+1. Create a file with a double extension:
+
+```markdown
+## <!-- index.html.md -->
+
+## model: gpt-4o-mini
+
+Create a simple landing page for a developer portfolio.
+Include a hero section, about section, and contact form.
+Use modern CSS with a dark theme.
+```
+
+2. Generate the GitHub Action:
+
+```bash
+nlang init
+```
+
+3. Set your API key in GitHub repo Settings → Secrets → `OPENAI_API_KEY`
+
+4. Push — your files will be built automatically!
+
+## How It Works
+
+### Double Extensions
+
+The **last extension** determines the executor, everything before it is the output format:
+
+| Source File      | Executor             | Output        |
+| ---------------- | -------------------- | ------------- |
+| `index.html.md`  | LLM prompt           | `index.html`  |
+| `styles.css.md`  | LLM prompt           | `styles.css`  |
+| `data.json.js`   | Node.js              | `data.json`   |
+| `readme.md.md`   | LLM prompt           | `readme.md`   |
+| `sitemap.xml.ts` | Node.js (TypeScript) | `sitemap.xml` |
+
+### Markdown Executor (LLM)
+
+Markdown files are sent as prompts to an LLM. Configure with **frontmatter**:
+
+```markdown
+---
+model: gpt-4o
+temperature: 0.7
+max_tokens: 8192
+system: "You are an expert web developer."
+cacheTtl: 86400
+---
+
+Your prompt here...
+```
+
+### JavaScript/TypeScript Executor
+
+JS/TS files export a function that returns the output:
+
+```javascript
+// data.json.js
+export default async function (ctx) {
+  const response = await fetch("https://api.example.com/data");
+  const data = await response.json();
+  return JSON.stringify(data, null, 2);
+}
+```
+
+The `ctx` object contains:
+
+- `deps` — resolved dependency contents
+- `variables` — variable values for this variant
+- `config` — merged nlang.json configuration
+- `rootDir` — project root path
+- `env` — environment variables
+
+### Dependencies with `@{path}`
+
+Reference other files in your prompts:
+
+```markdown
+<!-- components.html.md -->
+
+Create HTML components following this design system:
+
+@{design-tokens.json}
+
+And matching these TypeScript types:
+
+@{src/types.ts}
+```
+
+Files are built in dependency order. If `design-tokens.json` is itself generated (e.g., from `design-tokens.json.md`), it will be built first.
+
+You can also reference URLs:
+
+```markdown
+@{https://raw.githubusercontent.com/user/repo/main/schema.json}
+```
+
+### Variables with `[name]`
+
+Use bracket syntax in paths for templated builds:
+
+```
+blog/
+  name.json          # ["hello-world", "getting-started", "advanced-tips"]
+  [name].html.md     # Template that uses [name] in the prompt
+```
+
+The `[name].html.md` file will be executed once for each value in `name.json`, producing:
+
+- `blog/hello-world.html`
+- `blog/getting-started.html`
+- `blog/advanced-tips.html`
+
+### Cron Schedules
+
+Add a `trigger` to frontmatter for scheduled rebuilds:
+
+```markdown
+---
+trigger: "0 */6 * * *"
+---
+
+Fetch the latest news and generate an HTML summary...
+```
+
+When you run `nlang init`, this is picked up and added to the GitHub Action schedule.
+
+### Configuration: `nlang.json`
+
+Place `nlang.json` in any directory. More specific configs override parent configs:
+
+```json
+{
+  "model": "gpt-4o",
+  "temperature": 0,
+  "cacheTtl": 3600,
+  "baseURL": "https://api.openai.com/v1",
+  "system": "You are a helpful assistant."
+}
+```
+
+Config resolution order (later wins):
+
+1. `~/.nlang` (global)
+2. `./nlang.json` (project root)
+3. `./subdir/nlang.json` (closer to file)
+4. File frontmatter (highest priority)
+
+### Caching
+
+LLM responses are cached by content hash with configurable TTL:
+
+- Default TTL: **1 hour** (3600s)
+- When MCP is enabled: **no cache** by default
+- Override with `cacheTtl` in frontmatter or `nlang.json`
+- Set `cacheTtl: 0` to disable caching
+- Set `cacheTtl: -1` for infinite cache (only invalidated by content changes)
+
+## CLI
+
+```bash
+# Generate GitHub Action workflow
+nlang init
+
+# Build all executable files
+nlang build
+
+# Build a specific file and its dependency chain
+nlang build --file blog/[name].html.md
+
+# Dry run — show execution plan without running
+nlang build --dry-run
+
+# Specify project directory
+nlang build -d /path/to/project
+```
+
+## Environment Variables
+
+| Variable         | Description                                      |
+| ---------------- | ------------------------------------------------ |
+| `OPENAI_API_KEY` | OpenAI API key                                   |
+| `LLM_API_KEY`    | Alternative API key (for OpenAI-compatible APIs) |
+
+## Example Project
+
+```
+my-site/
+├── nlang.json              # {"model": "gpt-4o-mini"}
+├── index.html.md            # Landing page prompt
+├── styles.css.md            # CSS prompt (references index.html.md output)
+├── blog/
+│   ├── name.json            # ["intro", "tutorial"]
+│   ├── [name].html.md       # Blog post template
+│   └── index.html.js        # Blog index (reads generated posts)
+├── data/
+│   └── api-data.json.ts     # Fetches and transforms API data
+└── dist/                    # ← Build output (auto-generated)
+    ├── index.html
+    ├── styles.css
+    ├── blog/
+    │   ├── intro.html
+    │   ├── tutorial.html
+    │   └── index.html
+    └── data/
+        └── api-data.json
+```

package/bin/nlang.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { parseArgs } from "node:util";
+import { resolve } from "node:path";
+import { initWorkflow } from "../src/init.js";
+import { build } from "../src/build.js";
+
+const { values, positionals } = parseArgs({
+  allowPositionals: true,
+  options: {
+    dir: { type: "string", short: "d", default: "." },
+    help: { type: "boolean", short: "h", default: false },
+    "dry-run": { type: "boolean", default: false },
+    file: { type: "string", short: "f" }
+  }
+});
+
+const command = positionals[0];
+
+if (values.help || !command) {
+  console.log(`
+nlang - Executable Extensions
+
+Commands:
+  init      Scan repo and generate .github/workflows/nlang.yml
+  build     Execute all double-extension files in dependency order
+  
+Options:
+  -d, --dir <path>    Root directory (default: .)
+  -f, --file <path>   Build only a specific file (and its dependencies)
+  --dry-run            Show what would be executed without running
+  -h, --help           Show this help
+`);
+  process.exit(0);
+}
+
+const rootDir = resolve(values.dir);
+
+if (command === "init") {
+  await initWorkflow(rootDir);
+} else if (command === "build") {
+  await build(rootDir, { dryRun: values["dry-run"], file: values.file });
+} else {
+  console.error(`Unknown command: ${command}`);
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "nlang-cli",
+  "version": "0.1.0",
+  "description": "Executable Extensions - Build system for double-extension files",
+  "type": "module",
+  "bin": {
+    "nlang": "./bin/nlang.js"
+  },
+  "scripts": {
+    "build": "node src/build.js",
+    "init": "node bin/nlang.js init",
+    "test": "node --test src/__tests__/"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "glob": "^10.3.10",
+    "openai": "^4.73.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/build.js

@@ -0,0 +1,286 @@
+import { scanFiles, loadConfig } from "./scanner.js";
+import { buildExecutionGraph, getSubgraph } from "./graph.js";
+import { loadCache, saveCache, computeHash, isCacheValid } from "./cache.js";
+import { executeMarkdown } from "./executors/markdown.js";
+import { executeJavaScript } from "./executors/javascript.js";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { existsSync } from "node:fs";
+
+/**
+ * @param {string} rootDir
+ * @param {{ dryRun?: boolean, file?: string }} opts
+ */
+export async function build(rootDir, opts = {}) {
+  console.log(`\n🔨 nlang build starting in ${rootDir}\n`);
+
+  // 1. Scan for executable files
+  let allFiles = await scanFiles(rootDir);
+  console.log(`📂 Found ${allFiles.length} executable file(s)\n`);
+
+  if (allFiles.length === 0) {
+    console.log("Nothing to build.");
+    return;
+  }
+
+  // 2. If targeting a specific file, get its subgraph
+  let files = allFiles;
+  if (opts.file) {
+    files = getSubgraph(allFiles, opts.file);
+    console.log(
+      `🎯 Building subgraph for ${opts.file}: ${files.length} file(s)\n`
+    );
+  }
+
+  // 3. Expand variables — creates virtual file entries for each variable value
+  files = await expandVariables(files, rootDir);
+
+  // 4. Build execution graph
+  const { layers } = buildExecutionGraph(files);
+  console.log(`📊 Execution plan: ${layers.length} layer(s)\n`);
+  for (let i = 0; i < layers.length; i++) {
+    console.log(
+      `  Layer ${i + 1}: ${layers[i].map((f) => f.relativePath).join(", ")}`
+    );
+  }
+  console.log();
+
+  if (opts.dryRun) {
+    console.log("🏃 Dry run — not executing.");
+    return;
+  }
+
+  // 5. Load cache
+  const cache = await loadCache(rootDir);
+
+  // 6. Execute layer by layer
+  /** @type {Map<string, string>} - output path -> content */
+  const outputs = new Map();
+
+  for (let i = 0; i < layers.length; i++) {
+    const layer = layers[i];
+    console.log(`\n⚡ Executing layer ${i + 1}/${layers.length}...`);
+
+    await Promise.all(
+      layer.map(async (file) => {
+        try {
+          const result = await executeFile(file, rootDir, cache, outputs);
+          const outputPath = file.relativePath.slice(
+            0,
+            -file.executorExtension.length
+          );
+          outputs.set(outputPath, result);
+          outputs.set(file.relativePath, result);
+        } catch (err) {
+          console.error(`  ❌ ${file.relativePath}: ${err.message}`);
+        }
+      })
+    );
+  }
+
+  // 7. Write output files
+  console.log(`\n📝 Writing ${outputs.size / 2} output file(s)...\n`);
+  const distDir = join(rootDir, "dist");
+  await mkdir(distDir, { recursive: true });
+
+  for (const [relPath, content] of outputs) {
+    // Skip the .xyz.md paths, only write the output paths (without executor ext)
+    if (
+      relPath.endsWith(".md") ||
+      relPath.endsWith(".js") ||
+      relPath.endsWith(".ts")
+    ) {
+      // Check if this is a source path (has double extension)
+      const parts = relPath.split(".");
+      if (parts.length > 2) continue;
+    }
+
+    const outPath = join(distDir, relPath);
+    await mkdir(dirname(outPath), { recursive: true });
+    await writeFile(outPath, content);
+    console.log(`  ✅ dist/${relPath}`);
+  }
+
+  // 8. Save cache
+  await saveCache(rootDir, cache);
+  console.log(`\n✨ Build complete!\n`);
+}
+
+/**
+ * Execute a single file.
+ * @param {import('./scanner.js').ExecutableFile} file
+ * @param {string} rootDir
+ * @param {Map<string, import('./cache.js').CacheEntry>} cache
+ * @param {Map<string, string>} outputs - already-built outputs
+ * @returns {Promise<string>}
+ */
+async function executeFile(file, rootDir, cache, outputs) {
+  const config = await loadConfig(file.relativePath, rootDir);
+
+  // Resolve dependencies from outputs or filesystem
+  /** @type {Record<string, string>} */
+  const resolvedDeps = {};
+  for (const dep of file.dependencies) {
+    if (outputs.has(dep)) {
+      resolvedDeps[dep] = outputs.get(dep);
+    } else {
+      // Try reading from filesystem
+      try {
+        resolvedDeps[dep] = await readFile(join(rootDir, dep), "utf-8");
+      } catch {
+        // Try from dist
+        try {
+          resolvedDeps[dep] = await readFile(
+            join(rootDir, "dist", dep),
+            "utf-8"
+          );
+        } catch {
+          console.warn(
+            `  ⚠️  Dependency ${dep} not found for ${file.relativePath}`
+          );
+        }
+      }
+    }
+  }
+
+  // Compute content hash for caching
+  const fullContent =
+    file.content +
+    JSON.stringify(resolvedDeps) +
+    JSON.stringify(file._variables || {});
+  const hash = computeHash(fullContent, config);
+
+  // Determine TTL: if MCP is used, default to 0 (no cache) unless explicitly set
+  const usesMcp = file.frontmatter.mcp || config.mcp;
+  const defaultTtl = usesMcp ? 0 : 3600; // 1 hour default
+  const ttl = file.frontmatter.cacheTtl ?? config.cacheTtl ?? defaultTtl;
+
+  // Check cache
+  const cacheKey = file.relativePath + (file._variantKey || "");
+  const cached = cache.get(cacheKey);
+  if (isCacheValid(cached, hash)) {
+    console.log(`  💾 ${file.relativePath} (cached)`);
+    return cached.result;
+  }
+
+  console.log(`  🔧 ${file.relativePath}`);
+
+  let result;
+
+  if (file.executorExtension === ".md") {
+    result = await executeMarkdown({
+      content: file.content,
+      frontmatter: file.frontmatter,
+      config,
+      rootDir,
+      resolvedDeps,
+      variables: file._variables || {}
+    });
+  } else if (
+    file.executorExtension === ".js" ||
+    file.executorExtension === ".ts"
+  ) {
+    result = await executeJavaScript({
+      filePath: file.path,
+      content: file.content,
+      resolvedDeps,
+      variables: file._variables || {},
+      config,
+      rootDir
+    });
+  } else {
+    throw new Error(`Unknown executor: ${file.executorExtension}`);
+  }
+
+  // Update cache
+  cache.set(cacheKey, {
+    hash,
+    result,
+    timestamp: Date.now(),
+    ttl
+  });
+
+  return result;
+}
+
+/**
+ * Expand [variable] files into multiple virtual file entries.
+ * @param {import('./scanner.js').ExecutableFile[]} files
+ * @param {string} rootDir
+ * @returns {Promise<import('./scanner.js').ExecutableFile[]>}
+ */
+async function expandVariables(files, rootDir) {
+  /** @type {import('./scanner.js').ExecutableFile[]} */
+  const expanded = [];
+
+  for (const file of files) {
+    if (file.variables.length === 0) {
+      expanded.push(file);
+      continue;
+    }
+
+    // Load variable values
+    /** @type {Record<string, string[]>} */
+    const varValues = {};
+    let hasAllValues = true;
+
+    for (const v of file.variables) {
+      const valuesPath = join(rootDir, v.valuesFile);
+      try {
+        const raw = await readFile(valuesPath, "utf-8");
+        const values = JSON.parse(raw);
+        if (Array.isArray(values)) {
+          varValues[v.name] = values;
+        } else {
+          console.warn(`  ⚠️  ${v.valuesFile} should contain a JSON array`);
+          hasAllValues = false;
+        }
+      } catch {
+        console.warn(
+          `  ⚠️  Variable file ${v.valuesFile} not found for ${file.relativePath}`
+        );
+        hasAllValues = false;
+      }
+    }
+
+    if (!hasAllValues) {
+      expanded.push(file);
+      continue;
+    }
+
+    // Generate combinations (for simplicity, handle single variable; multi-var is a cartesian product)
+    const varNames = Object.keys(varValues);
+    const combos = cartesian(varNames.map((n) => varValues[n]));
+
+    for (const combo of combos) {
+      const vars = {};
+      let path = file.relativePath;
+      for (let j = 0; j < varNames.length; j++) {
+        vars[varNames[j]] = combo[j];
+        path = path.replaceAll(`[${varNames[j]}]`, combo[j]);
+      }
+
+      expanded.push({
+        ...file,
+        relativePath: path,
+        _variables: vars,
+        _variantKey: JSON.stringify(vars),
+        variables: [] // already expanded
+      });
+    }
+  }
+
+  return expanded;
+}
+
+/**
+ * Cartesian product of arrays.
+ * @param {string[][]} arrays
+ * @returns {string[][]}
+ */
+function cartesian(arrays) {
+  if (arrays.length === 0) return [[]];
+  const [first, ...rest] = arrays;
+  const restCombos = cartesian(rest);
+  return first.flatMap((val) => restCombos.map((combo) => [val, ...combo]));
+}

package/src/cache.js

@@ -0,0 +1,69 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { createHash } from "node:crypto";
+
+const CACHE_DIR = ".nlang-cache";
+
+/**
+ * @typedef {{
+ *   hash: string,
+ *   result: string,
+ *   timestamp: number,
+ *   ttl: number,
+ * }} CacheEntry
+ */
+
+/**
+ * @param {string} rootDir
+ * @returns {Promise<Map<string, CacheEntry>>}
+ */
+export async function loadCache(rootDir) {
+  const cachePath = join(rootDir, CACHE_DIR, "cache.json");
+  try {
+    const raw = await readFile(cachePath, "utf-8");
+    const entries = JSON.parse(raw);
+    return new Map(Object.entries(entries));
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * @param {string} rootDir
+ * @param {Map<string, CacheEntry>} cache
+ */
+export async function saveCache(rootDir, cache) {
+  const cachePath = join(rootDir, CACHE_DIR, "cache.json");
+  await mkdir(dirname(cachePath), { recursive: true });
+  const obj = Object.fromEntries(cache);
+  await writeFile(cachePath, JSON.stringify(obj, null, 2));
+}
+
+/**
+ * Get a cache key hash for a file's content + dependencies.
+ * @param {string} content
+ * @param {Record<string, any>} config
+ * @returns {string}
+ */
+export function computeHash(content, config = {}) {
+  const hash = createHash("sha256");
+  hash.update(content);
+  hash.update(JSON.stringify(config));
+  return hash.digest("hex").slice(0, 16);
+}
+
+/**
+ * Check if a cache entry is still valid.
+ * @param {CacheEntry | undefined} entry
+ * @param {string} currentHash
+ * @returns {boolean}
+ */
+export function isCacheValid(entry, currentHash) {
+  if (!entry) return false;
+  if (entry.hash !== currentHash) return false;
+  if (entry.ttl > 0) {
+    const elapsed = Date.now() - entry.timestamp;
+    if (elapsed > entry.ttl * 1000) return false;
+  }
+  return true;
+}

package/src/executors/javascript.js

@@ -0,0 +1,122 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { join, dirname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { tmpdir } from "node:os";
+import { randomBytes } from "node:crypto";
+
+/**
+ * Execute a .js or .ts file and capture its output.
+ *
+ * The file should export a default function or be a script that returns/logs content.
+ * Convention: export default async function(context) { return "file content" }
+ *
+ * @param {object} opts
+ * @param {string} opts.filePath - absolute path to the .js/.ts file
+ * @param {string} opts.content - raw file content
+ * @param {Record<string, string>} opts.resolvedDeps - map of dep path -> content
+ * @param {Record<string, string>} opts.variables - map of variable name -> value
+ * @param {Record<string, any>} opts.config
+ * @param {string} opts.rootDir
+ * @returns {Promise<string>}
+ */
+export async function executeJavaScript({
+  filePath,
+  content,
+  resolvedDeps,
+  variables,
+  config,
+  rootDir
+}) {
+  // For .ts files, we rely on Node 22+ --experimental-strip-types or tsx
+  // For now, try direct import first
+
+  const context = {
+    deps: resolvedDeps,
+    variables,
+    config,
+    rootDir,
+    env: process.env
+  };
+
+  try {
+    // Dynamic import
+    const fileUrl = pathToFileURL(filePath).href;
+    const mod = await import(fileUrl);
+
+    if (typeof mod.default === "function") {
+      const result = await mod.default(context);
+      if (typeof result === "string") return result;
+      if (typeof result === "object") return JSON.stringify(result, null, 2);
+      return String(result);
+    }
+
+    if (typeof mod.default === "string") {
+      return mod.default;
+    }
+
+    // If module has a named export 'output'
+    if (typeof mod.output === "function") {
+      const result = await mod.output(context);
+      return typeof result === "string"
+        ? result
+        : JSON.stringify(result, null, 2);
+    }
+
+    if (typeof mod.output === "string") {
+      return mod.output;
+    }
+
+    throw new Error(
+      `${filePath}: No default export or 'output' export found. ` +
+        `Export a function or string: export default async function(ctx) { return "..." }`
+    );
+  } catch (err) {
+    // If import fails for .ts, try with tsx if available
+    if (filePath.endsWith(".ts")) {
+      return executeWithTsx(filePath, context);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Fallback: execute .ts file via tsx/npx tsx
+ * @param {string} filePath
+ * @param {object} context
+ * @returns {Promise<string>}
+ */
+async function executeWithTsx(filePath, context) {
+  const { execSync } = await import("node:child_process");
+
+  // Write a wrapper that imports the file and prints the result
+  const tmpFile = join(tmpdir(), `nlang-${randomBytes(4).toString("hex")}.mjs`);
+  const wrapper = `
+import { pathToFileURL } from 'node:url';
+const mod = await import(pathToFileURL(${JSON.stringify(filePath)}).href);
+const ctx = ${JSON.stringify(context)};
+let result;
+if (typeof mod.default === 'function') result = await mod.default(ctx);
+else if (typeof mod.default === 'string') result = mod.default;
+else if (typeof mod.output === 'function') result = await mod.output(ctx);
+else if (typeof mod.output === 'string') result = mod.output;
+else throw new Error('No default or output export');
+if (typeof result !== 'string') result = JSON.stringify(result, null, 2);
+process.stdout.write(result);
+`;
+
+  await writeFile(tmpFile, wrapper);
+
+  try {
+    const result = execSync(`npx tsx ${tmpFile}`, {
+      encoding: "utf-8",
+      cwd: dirname(filePath),
+      timeout: 60000
+    });
+    return result;
+  } finally {
+    try {
+      const { unlink } = await import("node:fs/promises");
+      await unlink(tmpFile);
+    } catch {}
+  }
+}

package/src/executors/markdown.js

@@ -0,0 +1,104 @@
+import OpenAI from "openai";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Execute a markdown file by sending it to an LLM.
+ *
+ * @param {object} opts
+ * @param {string} opts.content - The markdown prompt (frontmatter stripped)
+ * @param {Record<string, any>} opts.frontmatter
+ * @param {Record<string, any>} opts.config - merged nlang.json config
+ * @param {string} opts.rootDir
+ * @param {Record<string, string>} opts.resolvedDeps - map of dep path -> content
+ * @param {Record<string, string>} opts.variables - map of variable name -> value
+ * @returns {Promise<string>}
+ */
+export async function executeMarkdown({
+  content,
+  frontmatter,
+  config,
+  rootDir,
+  resolvedDeps,
+  variables
+}) {
+  // Replace @{path} references with resolved content
+  let prompt = content;
+  for (const [depPath, depContent] of Object.entries(resolvedDeps)) {
+    prompt = prompt.replaceAll(`@{${depPath}}`, depContent);
+  }
+
+  // Replace [variable] references
+  for (const [varName, varValue] of Object.entries(variables)) {
+    prompt = prompt.replaceAll(`[${varName}]`, varValue);
+  }
+
+  // Also handle @{URL} references by fetching them
+  const urlRegex = /@\{(https?:\/\/[^}]+)\}/g;
+  let urlMatch;
+  while ((urlMatch = urlRegex.exec(prompt)) !== null) {
+    const url = urlMatch[1];
+    try {
+      const resp = await fetch(url);
+      const text = await resp.text();
+      prompt = prompt.replaceAll(`@{${url}}`, text);
+    } catch (err) {
+      console.warn(`⚠️  Failed to fetch ${url}: ${err.message}`);
+    }
+  }
+
+  // Determine model and API settings
+  const model = frontmatter.model || config.model || "gpt-4o-mini";
+  const baseURL = frontmatter.baseURL || config.baseURL || undefined;
+  const apiKey =
+    frontmatter.apiKey ||
+    config.apiKey ||
+    process.env.OPENAI_API_KEY ||
+    process.env.LLM_API_KEY;
+
+  if (!apiKey) {
+    throw new Error(
+      "No API key found. Set OPENAI_API_KEY or LLM_API_KEY env var, or configure in nlang.json"
+    );
+  }
+
+  const client = new OpenAI({
+    apiKey,
+    ...(baseURL ? { baseURL } : {})
+  });
+
+  const systemPrompt =
+    frontmatter.system ||
+    config.system ||
+    "You are a build tool. Output ONLY the requested file content, no explanations, no markdown fences unless the output format is markdown.";
+
+  console.log(`  🤖 Calling ${model}...`);
+
+  const response = await client.chat.completions.create({
+    model,
+    messages: [
+      { role: "system", content: systemPrompt },
+      { role: "user", content: prompt }
+    ],
+    temperature: frontmatter.temperature ?? config.temperature ?? 0,
+    max_tokens: frontmatter.max_tokens ?? config.max_tokens ?? 4096
+  });
+
+  const result = response.choices[0]?.message?.content || "";
+
+  // Strip wrapping code fences if present and the output isn't markdown
+  return stripCodeFences(result);
+}
+
+/**
+ * Strip leading/trailing code fences from LLM output.
+ * e.g. ```html\n...\n``` -> ...
+ * @param {string} text
+ * @returns {string}
+ */
+function stripCodeFences(text) {
+  const trimmed = text.trim();
+  const match = trimmed.match(/^```\w*\n([\s\S]*?)\n```$/);
+  if (match) return match[1];
+  return trimmed;
+}

package/src/graph.js

@@ -0,0 +1,149 @@
+/**
+ * Build a dependency graph and return execution order.
+ * Returns layers of files that can be executed in parallel.
+ *
+ * @typedef {import('./scanner.js').ExecutableFile} ExecutableFile
+ */
+
+/**
+ * @param {ExecutableFile[]} files
+ * @returns {{ layers: ExecutableFile[][], order: ExecutableFile[] }}
+ */
+export function buildExecutionGraph(files) {
+  // Map relative paths to files (including output paths)
+  /** @type {Map<string, ExecutableFile>} */
+  const fileMap = new Map();
+  for (const file of files) {
+    fileMap.set(file.relativePath, file);
+    // Also map by output path (without executor extension)
+    const outputPath = file.relativePath.slice(
+      0,
+      -file.executorExtension.length,
+    );
+    fileMap.set(outputPath, file);
+  }
+
+  // Build adjacency list: file -> files it depends on
+  /** @type {Map<string, Set<string>>} */
+  const adj = new Map();
+  /** @type {Map<string, number>} */
+  const inDegree = new Map();
+
+  for (const file of files) {
+    const key = file.relativePath;
+    if (!adj.has(key)) adj.set(key, new Set());
+    if (!inDegree.has(key)) inDegree.set(key, 0);
+
+    for (const dep of file.dependencies) {
+      // Resolve dep to a known file
+      const depFile = fileMap.get(dep);
+      if (depFile && depFile.relativePath !== key) {
+        const depKey = depFile.relativePath;
+        if (!adj.has(depKey)) adj.set(depKey, new Set());
+        if (!inDegree.has(depKey)) inDegree.set(depKey, 0);
+
+        // dep must run before this file
+        adj.get(depKey).add(key);
+        inDegree.set(key, (inDegree.get(key) || 0) + 1);
+      }
+    }
+  }
+
+  // Kahn's algorithm — topological sort with layers for parallelism
+  /** @type {ExecutableFile[][]} */
+  const layers = [];
+  let queue = [];
+
+  for (const file of files) {
+    if ((inDegree.get(file.relativePath) || 0) === 0) {
+      queue.push(file.relativePath);
+    }
+  }
+
+  const visited = new Set();
+
+  while (queue.length > 0) {
+    const layer = [];
+    const nextQueue = [];
+
+    for (const key of queue) {
+      if (visited.has(key)) continue;
+      visited.add(key);
+      const file = files.find((f) => f.relativePath === key);
+      if (file) layer.push(file);
+
+      for (const neighbor of adj.get(key) || []) {
+        const newDegree = (inDegree.get(neighbor) || 1) - 1;
+        inDegree.set(neighbor, newDegree);
+        if (newDegree === 0) {
+          nextQueue.push(neighbor);
+        }
+      }
+    }
+
+    if (layer.length > 0) layers.push(layer);
+    queue = nextQueue;
+  }
+
+  // Check for cycles
+  if (visited.size < files.length) {
+    const unvisited = files.filter((f) => !visited.has(f.relativePath));
+    console.error(
+      "⚠️  Circular dependencies detected in:",
+      unvisited.map((f) => f.relativePath),
+    );
+  }
+
+  const order = layers.flat();
+  return { layers, order };
+}
+
+/**
+ * Given a specific file, find all its transitive dependencies and dependants.
+ * @param {ExecutableFile[]} allFiles
+ * @param {string} targetPath - relative path
+ * @returns {ExecutableFile[]}
+ */
+export function getSubgraph(allFiles, targetPath) {
+  /** @type {Map<string, ExecutableFile>} */
+  const fileMap = new Map();
+  for (const f of allFiles) {
+    fileMap.set(f.relativePath, f);
+    const outputPath = f.relativePath.slice(0, -f.executorExtension.length);
+    fileMap.set(outputPath, f);
+  }
+
+  const needed = new Set();
+
+  // Collect transitive dependencies (upstream)
+  function collectDeps(path) {
+    if (needed.has(path)) return;
+    needed.add(path);
+    const file = fileMap.get(path);
+    if (!file) return;
+    for (const dep of file.dependencies) {
+      const depFile = fileMap.get(dep);
+      if (depFile) collectDeps(depFile.relativePath);
+    }
+  }
+
+  // Collect transitive dependants (downstream)
+  function collectDependants(path) {
+    if (needed.has(path)) return;
+    needed.add(path);
+    for (const f of allFiles) {
+      const outputPath = path.slice(
+        0,
+        -((fileMap.get(path)?.executorExtension || "").length || 0),
+      );
+      if (f.dependencies.includes(path) || f.dependencies.includes(outputPath)) {
+        collectDependants(f.relativePath);
+      }
+    }
+  }
+
+  collectDeps(targetPath);
+  collectDependants(targetPath);
+
+  return allFiles.filter((f) => needed.has(f.relativePath));
+}

package/src/init.js

@@ -0,0 +1,162 @@
+import { scanFiles } from "./scanner.js";
+import { writeFile, mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+/**
+ * Generate .github/workflows/nlang.yml based on discovered files.
+ * @param {string} rootDir
+ */
+export async function initWorkflow(rootDir) {
+  console.log(`\n🔍 Scanning ${rootDir} for executable files...\n`);
+
+  const files = await scanFiles(rootDir);
+  console.log(`📂 Found ${files.length} executable file(s)`);
+
+  // Collect cron schedules
+  /** @type {Map<string, string[]>} - cron expression -> file paths */
+  const cronMap = new Map();
+
+  for (const file of files) {
+    if (file.cron) {
+      const existing = cronMap.get(file.cron) || [];
+      existing.push(file.relativePath);
+      cronMap.set(file.cron, existing);
+    }
+  }
+
+  console.log(`⏰ Found ${cronMap.size} cron schedule(s)`);
+  for (const [cron, paths] of cronMap) {
+    console.log(`  ${cron}: ${paths.join(", ")}`);
+  }
+
+  // Generate the workflow
+  const workflow = generateWorkflow(cronMap, files);
+
+  // Write it
+  const workflowDir = join(rootDir, ".github", "workflows");
+  await mkdir(workflowDir, { recursive: true });
+  const workflowPath = join(workflowDir, "nlang.yml");
+  await writeFile(workflowPath, workflow);
+
+  console.log(`\n✅ Generated ${workflowPath}\n`);
+  console.log(`Next steps:`);
+  console.log(
+    `  1. Set OPENAI_API_KEY (or LLM_API_KEY) in your repo's Settings → Secrets`
+  );
+  console.log(`  2. Commit and push the workflow file`);
+  console.log(
+    `  3. Your files will be built on push and on the configured schedules\n`
+  );
+}
+
+/**
+ * Generate the YAML workflow content.
+ * @param {Map<string, string[]>} cronMap
+ * @param {import('./scanner.js').ExecutableFile[]} files
+ * @returns {string}
+ */
+function generateWorkflow(cronMap, files) {
+  // Build schedule entries
+  const schedules = [];
+  const cronEntries = [...cronMap.entries()];
+
+  for (const [cron] of cronEntries) {
+    schedules.push(`    - cron: '${cron}'`);
+  }
+
+  const hasSchedules = schedules.length > 0;
+  const hasMdFiles = files.some((f) => f.executorExtension === ".md");
+  const hasTsFiles = files.some((f) => f.executorExtension === ".ts");
+
+  // Build the dispatch file mapping for cron triggers
+  // We use workflow_dispatch inputs to allow targeted builds
+  // For cron, we determine which files to build based on the schedule
+  const cronDispatchLogic = cronEntries
+    .map(([cron, paths], i) => {
+      const condition =
+        i === 0
+          ? `if [ "\${{ github.event.schedule }}" = "${cron}" ]; then`
+          : `elif [ \${{ github.event.schedule }}" = "${cron}" ]; then`;
+      // Build each file individually via --file flag
+      const buildCmds = paths
+        .map((p) => `            npx nlang build --file "${p}"`)
+        .join("\n");
+      return `          ${condition}\n${buildCmds}`;
+    })
+    .join("\n");
+
+  const yaml = `# Generated by nlang - Executable Extensions
+# https://github.com/nicely-defined/nlang
+#
+# This workflow builds double-extension files:
+# - .xyz.md files are sent to an LLM API
+# - .xyz.js/.ts files are executed in Node.js
+# Output is written to the dist/ directory.
+
+name: nlang build
+
+on:
+  push:
+    branches: [main, master]
+    paths-ignore:
+      - 'dist/**'
+      - '.nlang-cache/**'
+${hasSchedules ? `  schedule:\n${schedules.join("\n")}` : ""}
+  workflow_dispatch:
+    inputs:
+      file:
+        description: 'Specific file to build (optional)'
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install nlang
+        run: npm install -g nlang
+
+${hasTsFiles ? `      - name: Install tsx (for TypeScript support)\n        run: npm install -g tsx\n` : ""}
+      - name: Restore cache
+        uses: actions/cache@v4
+        with:
+          path: .nlang-cache
+          key: nlang-cache-\${{ github.sha }}
+          restore-keys: |
+            nlang-cache-
+
+      - name: Build
+        env:
+          OPENAI_API_KEY: \${{ secrets.OPENAI_API_KEY }}
+          LLM_API_KEY: \${{ secrets.LLM_API_KEY }}
+        run: |
+          if [ -n "\${{ github.event.inputs.file }}" ]; then
+            npx nlang build --file "\${{ github.event.inputs.file }}"
+${cronDispatchLogic ? `${cronDispatchLogic}\n          fi` : "          else\n            npx nlang build\n          fi"}${!cronDispatchLogic ? "" : `\n          else\n            npx nlang build\n          fi`}
+
+      - name: Commit and push output
+        run: |
+          git config user.name "nlang[bot]"
+          git config user.email "nlang[bot]@users.noreply.github.com"
+          git add dist/ .nlang-cache/
+          if git diff --staged --quiet; then
+            echo "No changes to commit"
+          else
+            git commit -m "nlang: build output [skip ci]"
+            git push
+          fi
+`;
+
+  return yaml;
+}

package/src/scanner.js

@@ -0,0 +1,192 @@
+import { glob } from "glob";
+import { readFile } from "node:fs/promises";
+import { join, basename, dirname, extname, relative } from "node:path";
+import matter from "gray-matter";
+
+/**
+ * Represents a discovered executable file.
+ * @typedef {{
+ *   path: string,
+ *   relativePath: string,
+ *   outputExtension: string,
+ *   executorExtension: string,
+ *   frontmatter: Record<string, any>,
+ *   content: string,
+ *   rawContent: string,
+ *   dependencies: string[],
+ *   variables: { name: string, valuesFile: string | null }[],
+ *   cron: string | null,
+ * }} ExecutableFile
+ */
+
+// Match files with 2+ extensions: e.g. foo.html.md, bar.json.js
+const DOUBLE_EXT_PATTERN = "**/*.*.*";
+
+// Executor extensions we know how to run
+const EXECUTOR_EXTENSIONS = new Set([".md", ".js", ".ts"]);
+
+/**
+ * Scan a directory for double-extension files.
+ * @param {string} rootDir
+ * @returns {Promise<ExecutableFile[]>}
+ */
+export async function scanFiles(rootDir) {
+  const files = await glob(DOUBLE_EXT_PATTERN, {
+    cwd: rootDir,
+    nodir: true,
+    ignore: ["node_modules/**", ".git/**", ".github/**", "dist/**", "build/**"]
+  });
+
+  /** @type {ExecutableFile[]} */
+  const executables = [];
+
+  for (const relPath of files) {
+    const fullPath = join(rootDir, relPath);
+    const name = basename(relPath);
+
+    // Get the last extension (executor) and everything before it (output)
+    const executorExt = extname(name);
+    if (!EXECUTOR_EXTENSIONS.has(executorExt)) continue;
+
+    const withoutExecutor = name.slice(0, -executorExt.length);
+    const outputExt = extname(withoutExecutor);
+    if (!outputExt) continue; // need at least 2 extensions
+
+    const rawContent = await readFile(fullPath, "utf-8");
+
+    // Parse frontmatter for .md files
+    let frontmatterData = {};
+    let content = rawContent;
+    if (executorExt === ".md") {
+      const parsed = matter(rawContent);
+      frontmatterData = parsed.data;
+      content = parsed.content;
+    } else {
+      content = rawContent;
+    }
+
+    // Extract @{path} dependencies
+    const dependencies = extractDependencies(content);
+
+    // Extract [variable] patterns from path
+    const variables = extractVariables(relPath, rootDir);
+
+    // Extract cron
+    const cron = frontmatterData.trigger || null;
+
+    executables.push({
+      path: fullPath,
+      relativePath: relPath,
+      outputExtension: outputExt,
+      executorExtension: executorExt,
+      frontmatter: frontmatterData,
+      content,
+      rawContent,
+      dependencies,
+      variables,
+      cron
+    });
+  }
+
+  return executables;
+}
+
+/**
+ * Extract @{path} and @{URL} references from content.
+ * @param {string} content
+ * @returns {string[]}
+ */
+function extractDependencies(content) {
+  const regex = /@\{([^}]+)\}/g;
+  const deps = [];
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const ref = match[1];
+    // Skip URLs — only keep local paths
+    if (!ref.startsWith("http://") && !ref.startsWith("https://")) {
+      deps.push(ref);
+    }
+  }
+  return deps;
+}
+
+/**
+ * Extract [variable] patterns from file path and look for companion JSON.
+ * @param {string} relPath
+ * @param {string} rootDir
+ * @returns {{ name: string, valuesFile: string | null }[]}
+ */
+function extractVariables(relPath, rootDir) {
+  const regex = /\[([^\]]+)\]/g;
+  const vars = [];
+  let match;
+  while ((match = regex.exec(relPath)) !== null) {
+    const varName = match[1];
+    // Look for companion JSON: same directory, varName.json
+    const dir = dirname(relPath);
+    const valuesFile = join(dir, `${varName}.json`);
+    vars.push({ name: varName, valuesFile });
+  }
+  return vars;
+}
+
+/**
+ * Load nlang.json config, walking up from file's directory to rootDir.
+ * More specific configs override less specific ones.
+ * @param {string} filePath - relative path of the file
+ * @param {string} rootDir
+ * @returns {Promise<Record<string, any>>}
+ */
+export async function loadConfig(filePath, rootDir) {
+  const parts = dirname(filePath).split("/").filter(Boolean);
+  const configPaths = [];
+
+  // From most specific to least specific
+  let current = "";
+  // Root config
+  configPaths.push(join(rootDir, "nlang.json"));
+  // Also check ~/.nlang (global)
+  const homeDir = process.env.HOME || process.env.USERPROFILE || "";
+  if (homeDir) {
+    configPaths.push(join(homeDir, ".nlang"));
+  }
+
+  // Build paths from root to the file's directory
+  const dirConfigs = [];
+  for (const part of parts) {
+    current = current ? join(current, part) : part;
+    dirConfigs.push(join(rootDir, current, "nlang.json"));
+  }
+
+  // Merge: global < root < dir1 < dir2 < ... < most_specific_dir
+  let merged = {};
+
+  // Global config (lowest priority)
+  if (homeDir) {
+    merged = await tryLoadJson(join(homeDir, ".nlang"), merged);
+  }
+
+  // Root config
+  merged = await tryLoadJson(join(rootDir, "nlang.json"), merged);
+
+  // Directory configs (most specific wins)
+  for (const configPath of dirConfigs) {
+    merged = await tryLoadJson(configPath, merged);
+  }
+
+  return merged;
+}
+
+/**
+ * @param {string} path
+ * @param {Record<string, any>} base
+ * @returns {Promise<Record<string, any>>}
+ */
+async function tryLoadJson(path, base) {
+  try {
+    const raw = await readFile(path, "utf-8");
+    return { ...base, ...JSON.parse(raw) };
+  } catch {
+    return base;
+  }
+}