human-to-code 0.0.1

package/.claude/settings.local.json

@@ -0,0 +1,12 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm --version)",
+      "Bash(git --version)",
+      "Bash(node --help)",
+      "Bash(node src/cli.ts --help)",
+      "Bash(node --test)",
+      "Bash(node src/cli.ts /private/tmp/claude-501/-Users-shazi-Projects-Human-To-Code/3580a972-a849-48c3-a57a-17d60a5c7ac2/scratchpad/fixture --provider openai)"
+    ]
+  }
+}

package/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+      # Zero runtime dependencies — nothing to install.
+      - name: Run tests
+        run: node --test

package/CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to human-to-code
+
+Thanks for helping out! This project is in early development, so issues, ideas, and PRs are all welcome.
+
+## Development setup
+
+You only need **Node ≥ 23.6** — it runs the TypeScript source directly, so there's no build step and there are **no dependencies to install**.
+
+```bash
+git clone https://github.com/sharjeelbaig/human-to-code
+cd human-to-code
+node src/cli.ts --help    # run the CLI
+node --test               # run the test suite
+```
+
+## Project layout
+
+| Path               | What it is                                                            |
+| ------------------ | --------------------------------------------------------------------- |
+| `src/config.ts`    | Structured JSON config loader + validator                             |
+| `src/discovery.ts` | Finds and classifies `.human` / `.strict.human` files; security gates |
+| `src/cli.ts`       | Command-line entry point                                              |
+| `test/`            | `node:test` suites                                                    |
+
+## The one rule that keeps the project safe
+
+The pipeline is `human → strict → code`. The LLM is confined to `human → strict`; the `strict → code` step is a **deterministic generator with no LLM and no network**.
+
+- Keep `strict → code` deterministic — same IR in, identical code out.
+- **Never add a raw-code passthrough** to the strict grammar. It's the one change that would let a malicious `.human` file smuggle arbitrary code past review. If you ever truly need one, it must be explicitly flagged and gated.
+
+## Submitting changes
+
+1. Open an issue first for anything non-trivial so we can agree on direction.
+2. Keep PRs focused; add or update `node:test` cases for behavior changes.
+3. Make sure `node --test` passes before pushing.
+
+## Reporting security issues
+
+Please don't open a public issue for vulnerabilities — see [SECURITY.md](SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the human-to-code authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Readme.md

@@ -0,0 +1,84 @@
+<p align="center">
+  <img src="assets/banner.svg" alt="human-to-code — write intent in plain language, compile it to real code" width="100%">
+</p>
+
+<p align="center">
+  <a href="#status--roadmap"><img alt="status: alpha" src="https://img.shields.io/badge/status-alpha-orange"></a>
+  <img alt="node >= 23.6" src="https://img.shields.io/badge/node-%E2%89%A5%2023.6-brightgreen">
+  <a href="LICENSE"><img alt="license: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="CONTRIBUTING.md"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen"></a>
+  <img alt="zero dependencies" src="https://img.shields.io/badge/deps-0-informational">
+</p>
+
+`human-to-code` turns natural-language **`.human`** files into TypeScript, JavaScript, or Python — not by piping your whole codebase through an LLM and hoping, but through a small, reviewable intermediate representation that keeps the output reproducible.
+
+```text
+foo.human    →    foo.strict.human    →    foo.ts
+plain English      strict IR (reviewed)      real code
+      └── LLM ──┘         └── deterministic compiler ──┘
+```
+
+The LLM only writes the **middle** layer. Turning that layer into code is a plain compiler: **same IR in, identical code out — every run.**
+
+## Why the middle layer?
+
+- 🔁 **Reproducible** — `strict → code` uses no LLM, so builds are bit-for-bit stable.
+- 🔗 **Coherent across files** — a shared symbol table keeps names and signatures aligned, so a function defined in one file is called by the same name in another.
+- 🛡️ **Safe to review** — you diff a small, constrained IR instead of trusting freeform generated code. See [SECURITY.md](SECURITY.md).
+
+## Quick start
+
+> [!WARNING]
+> **Alpha.** The deterministic core (config, discovery, CLI planning) works today. The `.human → strict → code` generators are in progress, and it isn't on npm yet.
+
+```bash
+git clone https://github.com/sharjeelbaig/human-to-code
+cd human-to-code
+node src/cli.ts --help        # Node >= 23.6 runs the TypeScript directly — no build step
+```
+
+Planned published usage:
+
+```bash
+npx human-to-code .           # compile every .human file in the project
+npx human-to-code --init      # write a default config
+npx human-to-code --check     # CI gate: fail if a .human has no strict IR
+```
+
+## Configuration
+
+`human-to-code.config.json` (plain JSON — never parsed by an LLM):
+
+```json
+{
+  "language": "typescript",
+  "filesToIgnore": ["node_modules", ".git", "dist"],
+  "allowNonHumanFiles": false,
+  "provider": { "name": "anthropic", "model": "claude-opus-4-8" }
+}
+```
+
+Provider credentials come from **environment variables**, never a committed file. `secrets.human` is git-ignored, and the tool refuses to run if it's git-tracked.
+
+## Status & roadmap
+
+- [x] Deterministic core — config, discovery, CLI, security gates
+- [ ] `.strict.human` grammar + parser
+- [ ] Deterministic `strict → code` backend (TypeScript first)
+- [ ] `human → strict` LLM front-end (constrained output, hash-locked)
+- [ ] `--watch`, cost reporting, more target languages
+
+<details>
+<summary>How it fits together (architecture)</summary>
+
+The one non-deterministic step (`human → strict`) is confined to a single LLM call whose output is a committed, diffable IR. Everything downstream is a deterministic compiler with snapshot tests. A hand-written `.strict.human` always wins over a generated one, so you can drop to precise control whenever you want. Full design notes live in the project plan.
+
+</details>
+
+## Contributing
+
+Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Run the tests with `node --test`.
+
+## License
+
+[MIT](LICENSE) © the human-to-code authors

package/SECURITY.md

@@ -0,0 +1,20 @@
+# Security Policy
+
+`human-to-code` reads natural-language files and produces source code that people run, so it treats security as a first-class concern.
+
+## The security model
+
+- **The LLM can only produce the strict IR, never code directly.** Turning the IR into code is deterministic. A malicious `.human` file can, at worst, produce malicious *strict*, which is a small, constrained, reviewable artifact — not freeform code.
+- **The strict grammar has no raw-code escape hatch.** This is what keeps the review step meaningful; see [CONTRIBUTING.md](CONTRIBUTING.md).
+- **Secrets never reach a provider.** `secrets.human` and git-ignored files are excluded from any prompt context, and the tool refuses to run if `secrets.human` is git-tracked. Prefer environment variables or your OS keychain for credentials.
+- **Filesystem safety.** Discovery never follows symlinks and stays within the project root.
+- **Endpoints must use TLS.** A custom provider `baseUrl` must be `https://`.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities **privately** — do not open a public issue.
+
+- Use [GitHub private security advisories](https://docs.github.com/en/code-security/security-advisories/guidance-on-reporting-and-writing-information-about-vulnerabilities/privately-reporting-a-security-vulnerability) on this repository, **or**
+- email the maintainers (add a contact address here before publishing).
+
+We'll acknowledge your report, investigate, and coordinate a fix and disclosure timeline with you.

package/assets/banner.svg

@@ -0,0 +1,38 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1280 360" width="1280" height="360" role="img" aria-label="human-to-code — write intent in plain language, compile it to real code">
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#0b1220"/>
+      <stop offset="1" stop-color="#111a2e"/>
+    </linearGradient>
+    <style>
+      .mono { font-family: 'SFMono-Regular','Menlo','Consolas',ui-monospace,monospace; }
+      .sans { font-family: 'Segoe UI',system-ui,-apple-system,'Helvetica Neue',sans-serif; }
+    </style>
+  </defs>
+
+  <rect x="0" y="0" width="1280" height="360" rx="24" fill="url(#bg)"/>
+  <rect x="0" y="0" width="1280" height="6" rx="3" fill="#38bdf8" opacity="0.9"/>
+
+  <text x="640" y="118" text-anchor="middle" class="mono" font-size="62" font-weight="700" fill="#f8fafc">human-to-code</text>
+  <text x="640" y="158" text-anchor="middle" class="sans" font-size="21" fill="#94a3b8">Write intent in plain language. Compile it to real code.</text>
+
+  <!-- pipeline: human -> strict -> code -->
+  <g>
+    <rect x="300" y="212" width="170" height="62" rx="14" fill="#f59e0b"/>
+    <text x="385" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#1c1206">human</text>
+
+    <text x="495" y="252" text-anchor="middle" class="sans" font-size="30" fill="#64748b">&#8594;</text>
+
+    <rect x="520" y="212" width="240" height="62" rx="14" fill="#38bdf8"/>
+    <text x="640" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#062033">strict</text>
+
+    <text x="785" y="252" text-anchor="middle" class="sans" font-size="30" fill="#64748b">&#8594;</text>
+
+    <rect x="810" y="212" width="170" height="62" rx="14" fill="#34d399"/>
+    <text x="895" y="251" text-anchor="middle" class="mono" font-size="24" font-weight="700" fill="#062018">code</text>
+  </g>
+
+  <text x="385" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">natural language</text>
+  <text x="640" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">reviewable IR &#183; deterministic</text>
+  <text x="895" y="304" text-anchor="middle" class="sans" font-size="15" fill="#64748b">TS &#183; JS &#183; Python</text>
+</svg>

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "human-to-code",
+  "version": "0.0.1",
+  "description": "Compile natural-language .human files to code via a strict intermediate representation.",
+  "type": "module",
+  "bin": {
+    "human-to-code": "src/cli.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "engines": {
+    "node": ">=23.6.0"
+  },
+  "scripts": {
+    "start": "node src/cli.ts",
+    "test": "node --test",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "codegen",
+    "compiler",
+    "llm",
+    "natural-language",
+    "dsl"
+  ],
+  "license": "MIT"
+}

package/src/cli.ts

@@ -0,0 +1,218 @@
+#!/usr/bin/env node
+/**
+ * human-to-code CLI (deterministic core).
+ *
+ * Implemented now: `--init`, discovery + planning report (`--dry-run` style),
+ * and `--check` (CI: are there human sources without an up-to-date strict IR?).
+ * The `human -> strict` and `strict -> code` steps are added in later build
+ * steps; until then the CLI reports the plan instead of generating code.
+ */
+
+import { parseArgs } from "node:util";
+import { writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  CONFIG_FILENAME,
+  ConfigError,
+  defaultConfigJson,
+  defaultModelFor,
+  loadConfig,
+} from "./config.ts";
+import { discover, secretsTrackedError } from "./discovery.ts";
+import type { ProviderName } from "./types.ts";
+
+const HELP = `human-to-code — compile .human files to code via a strict IR
+
+Usage:
+  human-to-code [path] [options]
+
+Arguments:
+  path                 Directory to scan (default: ".")
+
+Options:
+  --init               Write a default ${CONFIG_FILENAME} and exit
+  --dry-run            Show the plan without generating anything (default today)
+  --check              Exit non-zero if any .human lacks an up-to-date .strict.human
+  --file <path>        Restrict to a single source file
+  --provider <name>    Override provider (openai|anthropic|ollama|grok|gemini)
+  -h, --help           Show this help
+
+Exit codes: 0 ok · 1 error · 2 --check found stale/missing strict IR
+`;
+
+interface Cli {
+  path: string;
+  init: boolean;
+  dryRun: boolean;
+  check: boolean;
+  file?: string;
+  provider?: string;
+  help: boolean;
+}
+
+function parse(argv: string[]): Cli {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    allowPositionals: true,
+    options: {
+      init: { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      check: { type: "boolean", default: false },
+      file: { type: "string" },
+      provider: { type: "string" },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+  const cli: Cli = {
+    path: positionals[0] ?? ".",
+    init: values.init === true,
+    dryRun: values["dry-run"] === true,
+    check: values.check === true,
+    help: values.help === true,
+  };
+  if (typeof values.file === "string") cli.file = values.file;
+  if (typeof values.provider === "string") cli.provider = values.provider;
+  return cli;
+}
+
+const VALID_PROVIDERS: readonly ProviderName[] = [
+  "openai",
+  "anthropic",
+  "ollama",
+  "grok",
+  "gemini",
+];
+
+async function runInit(root: string): Promise<number> {
+  const target = join(root, CONFIG_FILENAME);
+  if (existsSync(target)) {
+    console.error(`${CONFIG_FILENAME} already exists — not overwriting.`);
+    return 1;
+  }
+  await writeFile(target, defaultConfigJson(), "utf8");
+  console.log(`Wrote ${CONFIG_FILENAME}.`);
+  return 0;
+}
+
+export async function run(argv: string[]): Promise<number> {
+  let cli: Cli;
+  try {
+    cli = parse(argv);
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    console.error(HELP);
+    return 1;
+  }
+
+  if (cli.help) {
+    console.log(HELP);
+    return 0;
+  }
+
+  const root = resolve(cli.path);
+
+  if (cli.init) {
+    return runInit(root);
+  }
+
+  // Load + validate config (structured JSON, never LLM-parsed).
+  let config;
+  try {
+    ({ config } = await loadConfig(root));
+  } catch (err) {
+    if (err instanceof ConfigError) {
+      console.error(`Config error: ${err.message}`);
+      return 1;
+    }
+    throw err;
+  }
+
+  if (cli.provider) {
+    if (!VALID_PROVIDERS.includes(cli.provider as ProviderName)) {
+      console.error(
+        `Unknown --provider "${cli.provider}". Valid: ${VALID_PROVIDERS.join(", ")}.`,
+      );
+      return 1;
+    }
+    // A provider override carries that provider's current default model,
+    // rather than silently keeping the previous provider's model id.
+    const name = cli.provider as ProviderName;
+    config.provider.name = name;
+    config.provider.model = defaultModelFor(name);
+    delete config.provider.baseUrl;
+  }
+
+  // Discover sources.
+  const result = await discover(root, config.filesToIgnore);
+
+  // Security gate: refuse to run if secrets.human is git-tracked.
+  if (result.secrets) {
+    const msg = secretsTrackedError(result.secrets);
+    if (msg) {
+      console.error(msg);
+      return 1;
+    }
+  }
+
+  const strictPaths = new Set(result.strict.map((f) => f.relPath));
+
+  // Which .human files have no corresponding strict IR yet?
+  const humanFiltered = cli.file
+    ? result.human.filter((f) => f.relPath === toPosixRel(root, cli.file!))
+    : result.human;
+
+  const missingStrict = humanFiltered.filter(
+    (f) => f.strictSibling && !strictPaths.has(f.strictSibling),
+  );
+
+  // --check: CI gate.
+  if (cli.check) {
+    if (missingStrict.length > 0) {
+      console.error(
+        `--check failed: ${missingStrict.length} human file(s) without a strict IR:`,
+      );
+      for (const f of missingStrict) console.error(`  ${f.relPath}`);
+      return 2;
+    }
+    console.log("--check passed: every .human has a .strict.human.");
+    return 0;
+  }
+
+  // Report the plan (generation is added in a later build step).
+  console.log(`Scanned ${result.root}`);
+  console.log(`Language: ${config.language}`);
+  console.log(
+    `Provider: ${config.provider.name} (${config.provider.model})`,
+  );
+  console.log(
+    `Found: ${humanFiltered.length} .human, ${result.strict.length} .strict.human, ` +
+      `${result.ignoredCount} ignored${result.secrets ? ", secrets.human present" : ""}`,
+  );
+  if (missingStrict.length > 0) {
+    console.log(`Would generate strict IR for ${missingStrict.length} file(s):`);
+    for (const f of missingStrict) console.log(`  ${f.relPath} -> ${f.strictSibling}`);
+  }
+  console.log(
+    "\nNote: human -> strict and strict -> code generation are not implemented yet.",
+  );
+  return 0;
+}
+
+function toPosixRel(root: string, file: string): string {
+  const abs = resolve(root, file);
+  return abs.slice(root.length + 1).split(/[\\/]/).join("/");
+}
+
+// Only run when invoked as a script (not when imported by tests).
+if (
+  import.meta.url === `file://${process.argv[1]}` ||
+  import.meta.filename === process.argv[1]
+) {
+  run(process.argv.slice(2))
+    .then((code) => process.exit(code))
+    .catch((err) => {
+      console.error(err instanceof Error ? err.stack ?? err.message : String(err));
+      process.exit(1);
+    });
+}

package/src/config.ts

@@ -0,0 +1,186 @@
+/**
+ * Structured config loader.
+ *
+ * Config is deterministic JSON (`human-to-code.config.json`), never parsed by
+ * an LLM — see plan §1.7 / §2. A hand-rolled validator keeps the tool
+ * dependency-free and gives precise error messages.
+ */
+
+import { readFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import type {
+  Config,
+  ProviderConfig,
+  ProviderName,
+  TargetLanguage,
+} from "./types.ts";
+
+export const CONFIG_FILENAME = "human-to-code.config.json";
+
+const LANGUAGES: readonly TargetLanguage[] = [
+  "typescript",
+  "javascript",
+  "python",
+];
+
+const PROVIDERS: readonly ProviderName[] = [
+  "openai",
+  "anthropic",
+  "ollama",
+  "grok",
+  "gemini",
+];
+
+/**
+ * Current, non-dated default model per provider. The Anthropic default is the
+ * current flagship — the README's `claude-3-5-sonnet-20241022` is retired.
+ */
+const DEFAULT_MODEL: Record<ProviderName, string> = {
+  anthropic: "claude-opus-4-8",
+  openai: "gpt-4o",
+  ollama: "llama3.2",
+  grok: "grok-4.1",
+  gemini: "gemini-2.5-pro",
+};
+
+/** The current default model id for a provider. */
+export function defaultModelFor(name: ProviderName): string {
+  return DEFAULT_MODEL[name];
+}
+
+export const DEFAULT_CONFIG: Config = {
+  language: "typescript",
+  filesToIgnore: ["node_modules", ".git", "dist"],
+  allowNonHumanFiles: false,
+  provider: {
+    name: "anthropic",
+    model: DEFAULT_MODEL.anthropic,
+  },
+};
+
+/** Thrown for any malformed config; message is safe to show the user. */
+export class ConfigError extends Error {}
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function validateProvider(raw: unknown): ProviderConfig {
+  if (!isObject(raw)) {
+    throw new ConfigError("`provider` must be an object.");
+  }
+  const name = raw.name;
+  if (typeof name !== "string" || !PROVIDERS.includes(name as ProviderName)) {
+    throw new ConfigError(
+      `\`provider.name\` must be one of: ${PROVIDERS.join(", ")}.`,
+    );
+  }
+  const providerName = name as ProviderName;
+
+  let model = raw.model;
+  if (model === undefined) {
+    model = DEFAULT_MODEL[providerName];
+  } else if (typeof model !== "string" || model.length === 0) {
+    throw new ConfigError("`provider.model` must be a non-empty string.");
+  }
+
+  const provider: ProviderConfig = { name: providerName, model: model as string };
+
+  if (raw.baseUrl !== undefined) {
+    if (typeof raw.baseUrl !== "string") {
+      throw new ConfigError("`provider.baseUrl` must be a string.");
+    }
+    // Enforce TLS — a bad base URL can serve poisoned strict (plan §3.7).
+    if (!raw.baseUrl.startsWith("https://")) {
+      throw new ConfigError("`provider.baseUrl` must use https://.");
+    }
+    provider.baseUrl = raw.baseUrl;
+  }
+
+  return provider;
+}
+
+/** Validate an already-parsed object into a fully-defaulted Config. */
+export function validateConfig(raw: unknown): Config {
+  if (!isObject(raw)) {
+    throw new ConfigError("Config root must be a JSON object.");
+  }
+
+  const config: Config = {
+    ...DEFAULT_CONFIG,
+    provider: { ...DEFAULT_CONFIG.provider },
+  };
+
+  if (raw.language !== undefined) {
+    if (
+      typeof raw.language !== "string" ||
+      !LANGUAGES.includes(raw.language as TargetLanguage)
+    ) {
+      throw new ConfigError(
+        `\`language\` must be one of: ${LANGUAGES.join(", ")}.`,
+      );
+    }
+    config.language = raw.language as TargetLanguage;
+  }
+
+  if (raw.filesToIgnore !== undefined) {
+    if (
+      !Array.isArray(raw.filesToIgnore) ||
+      !raw.filesToIgnore.every((f) => typeof f === "string")
+    ) {
+      throw new ConfigError("`filesToIgnore` must be an array of strings.");
+    }
+    config.filesToIgnore = raw.filesToIgnore as string[];
+  }
+
+  if (raw.allowNonHumanFiles !== undefined) {
+    if (typeof raw.allowNonHumanFiles !== "boolean") {
+      throw new ConfigError("`allowNonHumanFiles` must be a boolean.");
+    }
+    config.allowNonHumanFiles = raw.allowNonHumanFiles;
+  }
+
+  if (raw.provider !== undefined) {
+    config.provider = validateProvider(raw.provider);
+  }
+
+  return config;
+}
+
+/**
+ * Load config from `<root>/human-to-code.config.json`. Returns the defaults
+ * (with a flag) when no config file exists so first-run works with zero setup.
+ */
+export async function loadConfig(
+  root: string,
+): Promise<{ config: Config; fromFile: boolean }> {
+  const path = join(root, CONFIG_FILENAME);
+  if (!existsSync(path)) {
+    return {
+      config: { ...DEFAULT_CONFIG, provider: { ...DEFAULT_CONFIG.provider } },
+      fromFile: false,
+    };
+  }
+
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (err) {
+    throw new ConfigError(`Could not read ${CONFIG_FILENAME}: ${String(err)}`);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new ConfigError(`${CONFIG_FILENAME} is not valid JSON: ${String(err)}`);
+  }
+
+  return { config: validateConfig(parsed), fromFile: true };
+}
+
+/** Serialize the default config for `--init`. */
+export function defaultConfigJson(): string {
+  return JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n";
+}

package/src/discovery.ts

@@ -0,0 +1,186 @@
+/**
+ * File discovery for the deterministic core.
+ *
+ * Responsibilities (plan §3.3–3.4):
+ *  - Walk the project, classifying .human / .strict.human / config / secrets.
+ *  - Apply a name-based ignore denylist + best-effort .gitignore.
+ *  - Never follow symlinks (traversal safety).
+ *  - Provide a git-tracked-secrets check so the CLI can refuse to run.
+ *
+ * Discovery is side-effect free; the CLI decides what to do with the result.
+ */
+
+import { readdir } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { relative, resolve, sep } from "node:path";
+import { CONFIG_FILENAME } from "./config.ts";
+import type { DiscoveryResult, SourceFile, SourceKind } from "./types.ts";
+
+const SECRETS_FILENAME = "secrets.human";
+const HUMAN_CONFIG_FILENAME = "config.human";
+const STRICT_SUFFIX = ".strict.human";
+const HUMAN_SUFFIX = ".human";
+
+/** Names always skipped regardless of config. */
+const ALWAYS_IGNORE = new Set([".git", "node_modules", CONFIG_FILENAME]);
+
+function toPosix(p: string): string {
+  return sep === "/" ? p : p.split(sep).join("/");
+}
+
+function classify(basename: string): SourceKind | null {
+  if (basename === SECRETS_FILENAME) return "secrets";
+  if (basename === HUMAN_CONFIG_FILENAME) return "config";
+  if (basename.endsWith(STRICT_SUFFIX)) return "strict";
+  // A plain .human file that is not one of the special files above.
+  if (basename.endsWith(HUMAN_SUFFIX)) return "human";
+  return null;
+}
+
+function strictSiblingOf(relPath: string): string {
+  // foo.human -> foo.strict.human
+  return relPath.slice(0, -HUMAN_SUFFIX.length) + STRICT_SUFFIX;
+}
+
+/**
+ * Recursively collect candidate files. Directories/files whose basename is in
+ * `ignore` are skipped. Symlinks are never followed.
+ */
+async function walk(
+  root: string,
+  dir: string,
+  ignore: Set<string>,
+  out: SourceFile[],
+  counters: { ignored: number },
+): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const abs = resolve(dir, entry.name);
+
+    if (entry.isSymbolicLink()) {
+      counters.ignored++;
+      continue; // traversal safety — never follow symlinks
+    }
+
+    if (ignore.has(entry.name)) {
+      counters.ignored++;
+      continue;
+    }
+
+    if (entry.isDirectory()) {
+      await walk(root, abs, ignore, out, counters);
+      continue;
+    }
+
+    if (!entry.isFile()) continue;
+
+    const kind = classify(entry.name);
+    if (kind === null) {
+      // Not a file we track; not counted as "ignored" for reporting.
+      continue;
+    }
+
+    const relPath = toPosix(relative(root, abs));
+    const file: SourceFile = { absPath: abs, relPath, kind };
+    if (kind === "human") {
+      file.strictSibling = strictSiblingOf(relPath);
+    }
+    out.push(file);
+  }
+}
+
+/** Return the subset of relPaths that git considers ignored (best effort). */
+function gitIgnored(root: string, relPaths: string[]): Set<string> {
+  if (relPaths.length === 0) return new Set();
+  const inRepo = spawnSync(
+    "git",
+    ["-C", root, "rev-parse", "--is-inside-work-tree"],
+    { encoding: "utf8" },
+  );
+  if (inRepo.status !== 0 || inRepo.stdout.trim() !== "true") return new Set();
+
+  const res = spawnSync("git", ["-C", root, "check-ignore", "--stdin"], {
+    input: relPaths.join("\n"),
+    encoding: "utf8",
+  });
+  // Exit 0 => some ignored, 1 => none ignored, other => error (treat as none).
+  if (res.status !== 0 && res.status !== 1) return new Set();
+  return new Set(
+    res.stdout
+      .split("\n")
+      .map((l) => l.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Discover and classify all source files under `rootInput`.
+ *
+ * @param rootInput  directory to scan
+ * @param extraIgnore  config.filesToIgnore (name-based denylist)
+ */
+export async function discover(
+  rootInput: string,
+  extraIgnore: string[] = [],
+): Promise<DiscoveryResult> {
+  const root = resolve(rootInput);
+  const ignore = new Set<string>([...ALWAYS_IGNORE, ...extraIgnore]);
+
+  const found: SourceFile[] = [];
+  const counters = { ignored: 0 };
+  await walk(root, root, ignore, found, counters);
+
+  // Best-effort .gitignore filtering on top of the name denylist.
+  const ignored = gitIgnored(
+    root,
+    found.map((f) => f.relPath),
+  );
+  const kept = found.filter((f) => {
+    // Secrets are always surfaced (so we can enforce safety), even if ignored.
+    if (f.kind === "secrets") return true;
+    if (ignored.has(f.relPath)) {
+      counters.ignored++;
+      return false;
+    }
+    return true;
+  });
+
+  const result: DiscoveryResult = {
+    root,
+    human: kept.filter((f) => f.kind === "human"),
+    strict: kept.filter((f) => f.kind === "strict"),
+    ignoredCount: counters.ignored,
+  };
+  const secrets = kept.find((f) => f.kind === "secrets");
+  if (secrets) result.secrets = secrets;
+  return result;
+}
+
+/**
+ * Refuse to run if `secrets.human` is tracked by git — a committed secrets file
+ * is the mistake we most want to prevent (plan §3.3). No-op outside a git repo.
+ * @returns an error message if unsafe, otherwise null.
+ */
+export function secretsTrackedError(secret: SourceFile): string | null {
+  if (secret.kind !== "secrets") return null;
+  const root = resolve(secret.absPath, "..");
+  const res = spawnSync(
+    "git",
+    ["-C", root, "ls-files", "--error-unmatch", secret.relPath],
+    { encoding: "utf8" },
+  );
+  if (res.status === 0) {
+    return (
+      `Refusing to run: ${secret.relPath} is tracked by git. ` +
+      `Remove it with \`git rm --cached ${secret.relPath}\` and add it to .gitignore. ` +
+      `Prefer environment variables or your OS keychain for provider credentials.`
+    );
+  }
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+/** Public API surface for programmatic use. */
+
+export type {
+  Config,
+  ProviderConfig,
+  ProviderName,
+  TargetLanguage,
+  SourceFile,
+  SourceKind,
+  DiscoveryResult,
+} from "./types.ts";
+
+export {
+  loadConfig,
+  validateConfig,
+  defaultConfigJson,
+  DEFAULT_CONFIG,
+  CONFIG_FILENAME,
+  ConfigError,
+} from "./config.ts";
+
+export { discover, secretsTrackedError } from "./discovery.ts";

package/src/types.ts

@@ -0,0 +1,74 @@
+/**
+ * Shared types for human-to-code.
+ *
+ * The pipeline is:  .human --(LLM)--> .strict.human --(deterministic)--> code
+ * These types describe the deterministic core (config + discovery) only; the
+ * strict DSL and code generators are added in later build steps.
+ */
+
+export type TargetLanguage = "typescript" | "javascript" | "python";
+
+export type ProviderName =
+  | "openai"
+  | "anthropic"
+  | "ollama"
+  | "grok"
+  | "gemini";
+
+export interface ProviderConfig {
+  /** Which LLM provider drives the human -> strict step. */
+  name: ProviderName;
+  /** Model id. Configurable; defaults are current, not dated snapshots. */
+  model: string;
+  /** Optional override endpoint (e.g. Ollama Cloud). Must be https. */
+  baseUrl?: string;
+}
+
+export interface Config {
+  /** Target language for the deterministic code generator. */
+  language: TargetLanguage;
+  /** Glob-free directory/file names to skip during discovery (a denylist). */
+  filesToIgnore: string[];
+  /**
+   * If true, non-.human files carrying `@Human:` directives may also be
+   * processed. Off by default — it widens the surface area (see plan §1.6).
+   */
+  allowNonHumanFiles: boolean;
+  /** Provider used only for the human -> strict step. */
+  provider: ProviderConfig;
+}
+
+/** Classification of a source file found during discovery. */
+export type SourceKind =
+  /** A hand-written or generated strict IR file: `foo.strict.human`. */
+  | "strict"
+  /** A natural-language source file: `foo.human` (not `.strict.human`). */
+  | "human"
+  /** Reserved special files, never compiled and never sent to a provider. */
+  | "config"
+  | "secrets";
+
+export interface SourceFile {
+  /** Absolute path. */
+  absPath: string;
+  /** Path relative to the discovery root, using forward slashes. */
+  relPath: string;
+  kind: SourceKind;
+  /**
+   * For a `.human` file, the sibling `.strict.human` path that would take
+   * precedence if it exists. Undefined for non-human kinds.
+   */
+  strictSibling?: string;
+}
+
+export interface DiscoveryResult {
+  root: string;
+  /** Natural-language sources eligible for the human -> strict step. */
+  human: SourceFile[];
+  /** Strict IR sources (hand-written ones take precedence over generated). */
+  strict: SourceFile[];
+  /** The secrets file, if present. Never compiled, never sent to a provider. */
+  secrets?: SourceFile;
+  /** Files skipped by ignore rules, for reporting under --dry-run. */
+  ignoredCount: number;
+}

package/test/config.test.ts

@@ -0,0 +1,97 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, writeFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  validateConfig,
+  loadConfig,
+  ConfigError,
+  DEFAULT_CONFIG,
+  CONFIG_FILENAME,
+} from "../src/config.ts";
+
+test("validateConfig fills defaults from an empty object", () => {
+  const c = validateConfig({});
+  assert.equal(c.language, "typescript");
+  assert.equal(c.provider.name, "anthropic");
+  assert.equal(c.provider.model, "claude-opus-4-8");
+  assert.equal(c.allowNonHumanFiles, false);
+});
+
+test("validateConfig accepts a valid language", () => {
+  assert.equal(validateConfig({ language: "python" }).language, "python");
+});
+
+test("validateConfig rejects an unknown language", () => {
+  assert.throws(() => validateConfig({ language: "rust" }), ConfigError);
+});
+
+test("provider model defaults per provider", () => {
+  const c = validateConfig({ provider: { name: "openai" } });
+  assert.equal(c.provider.model, "gpt-4o");
+});
+
+test("validateConfig rejects an unknown provider", () => {
+  assert.throws(
+    () => validateConfig({ provider: { name: "cohere" } }),
+    ConfigError,
+  );
+});
+
+test("baseUrl must be https", () => {
+  assert.throws(
+    () =>
+      validateConfig({
+        provider: { name: "ollama", baseUrl: "http://ollama.com" },
+      }),
+    ConfigError,
+  );
+  const ok = validateConfig({
+    provider: { name: "ollama", baseUrl: "https://ollama.com" },
+  });
+  assert.equal(ok.provider.baseUrl, "https://ollama.com");
+});
+
+test("validateConfig rejects non-object root", () => {
+  assert.throws(() => validateConfig([]), ConfigError);
+  assert.throws(() => validateConfig("nope"), ConfigError);
+});
+
+test("loadConfig returns defaults when no file exists", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "h2c-cfg-"));
+  try {
+    const { config, fromFile } = await loadConfig(dir);
+    assert.equal(fromFile, false);
+    assert.deepEqual(config, DEFAULT_CONFIG);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig reads and validates a config file", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "h2c-cfg-"));
+  try {
+    await writeFile(
+      join(dir, CONFIG_FILENAME),
+      JSON.stringify({ language: "javascript", provider: { name: "gemini" } }),
+    );
+    const { config, fromFile } = await loadConfig(dir);
+    assert.equal(fromFile, true);
+    assert.equal(config.language, "javascript");
+    assert.equal(config.provider.name, "gemini");
+    assert.equal(config.provider.model, "gemini-2.5-pro");
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("loadConfig surfaces invalid JSON as ConfigError", async () => {
+  const dir = await mkdtemp(join(tmpdir(), "h2c-cfg-"));
+  try {
+    await writeFile(join(dir, CONFIG_FILENAME), "{ not json ");
+    await assert.rejects(() => loadConfig(dir), ConfigError);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/test/discovery.test.ts

@@ -0,0 +1,91 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile, symlink, rm } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { discover, secretsTrackedError } from "../src/discovery.ts";
+
+async function makeFixture(): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "h2c-disc-"));
+  await writeFile(join(root, "a.human"), "print hello");
+  await writeFile(join(root, "a.strict.human"), "fn printHello");
+  await writeFile(join(root, "b.human"), "print bye"); // no strict sibling
+  await writeFile(join(root, "secrets.human"), "API Key: sk-x");
+  await writeFile(join(root, "config.human"), "Language: typescript");
+  await writeFile(join(root, "human-to-code.config.json"), "{}");
+  await mkdir(join(root, "node_modules"));
+  await writeFile(join(root, "node_modules", "dep.human"), "ignored");
+  await mkdir(join(root, "sub"));
+  await writeFile(join(root, "sub", "c.human"), "nested");
+  try {
+    await symlink(join(root, "sub"), join(root, "linkdir"), "dir");
+  } catch {
+    // symlinks may be unavailable; the rest of the assertions still hold.
+  }
+  return root;
+}
+
+test("discover classifies files and applies ignore rules", async () => {
+  const root = await makeFixture();
+  try {
+    const r = await discover(root, ["node_modules", ".git", "dist"]);
+
+    const humanPaths = r.human.map((f) => f.relPath).sort();
+    assert.deepEqual(humanPaths, ["a.human", "b.human", "sub/c.human"]);
+
+    assert.deepEqual(
+      r.strict.map((f) => f.relPath),
+      ["a.strict.human"],
+    );
+
+    // node_modules/dep.human is ignored.
+    assert.ok(!humanPaths.includes("node_modules/dep.human"));
+
+    // The symlinked dir must not be followed (no duplicate c.human).
+    assert.ok(!humanPaths.includes("linkdir/c.human"));
+
+    // secrets.human is surfaced separately, never as a human source.
+    assert.ok(r.secrets);
+    assert.equal(r.secrets?.relPath, "secrets.human");
+
+    // strictSibling wiring.
+    const a = r.human.find((f) => f.relPath === "a.human");
+    assert.equal(a?.strictSibling, "a.strict.human");
+    const b = r.human.find((f) => f.relPath === "b.human");
+    assert.equal(b?.strictSibling, "b.strict.human");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("secretsTrackedError returns null when not in a git repo", async () => {
+  const root = await makeFixture();
+  try {
+    const r = await discover(root, ["node_modules"]);
+    assert.ok(r.secrets);
+    assert.equal(secretsTrackedError(r.secrets!), null);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test("secretsTrackedError refuses when secrets.human is git-tracked", async () => {
+  const root = await makeFixture();
+  try {
+    assert.equal(
+      spawnSync("git", ["-C", root, "init", "-q"]).status,
+      0,
+      "git init failed",
+    );
+    // Staging is enough for `git ls-files` to consider it tracked.
+    spawnSync("git", ["-C", root, "add", "secrets.human"]);
+
+    const r = await discover(root, ["node_modules"]);
+    assert.ok(r.secrets);
+    const msg = secretsTrackedError(r.secrets!);
+    assert.ok(msg && msg.includes("Refusing to run"));
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "lib": ["esnext"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["src", "test"]
+}