@agjs/tsforge 0.1.0

package/src/config/config.constants.ts

@@ -0,0 +1,9 @@
+/** The "flag on" sentinel + the env var names the harness recognizes. */
+export const FLAG_ON = "1";
+
+export const ENV_FLAG = {
+  noLspTools: "TSFORGE_NO_LSP_TOOLS",
+  legacyFeedback: "TSFORGE_LEGACY_FEEDBACK",
+  noAstgrep: "TSFORGE_NO_ASTGREP",
+  forceTools: "TSFORGE_FORCE_TOOLS",
+} as const;

package/src/config/flags.ts

@@ -0,0 +1,32 @@
+import { FLAG_ON, ENV_FLAG } from "./config.constants";
+
+/**
+ * The ONLY module that reads `process.env` for runtime flags. Read LIVE (on each
+ * call, not at import) so per-run/test env changes take effect. (Scripts read
+ * their own env directly — they're operational entry points, not library code.)
+ */
+function isOn(name: string): boolean {
+  return process.env[name] === FLAG_ON;
+}
+
+export const flags = {
+  /** Withhold the LSP nav tool set even on existing-code runs (A/B control). */
+  noLspTools: (): boolean => isOn(ENV_FLAG.noLspTools),
+  /** Force the legacy (mis-selected) gate-feedback parser (A/B control). */
+  legacyFeedback: (): boolean => isOn(ENV_FLAG.legacyFeedback),
+  /** Disable the ast-grep safe-idiom rewrite pass in settleGate (A/B control). */
+  noAstgrep: (): boolean => isOn(ENV_FLAG.noAstgrep),
+  /** FORCED-TOOLS experiment (A/B, default off): every gated-build turn runs
+   *  with tool_choice "required" + a `yield_status` stop tool, so output is
+   *  always grammar-constrained — the malformed-tool-call class can't occur. */
+  forceTools: (): boolean => isOn(ENV_FLAG.forceTools),
+  /** Hashline edit tool (content-hash-anchored line edits) with snapshot recovery
+   *  (A/B control, default ON — set to "0" to disable). */
+  hashlineEditTool: (): boolean => process.env.TSFORGE_HASHLINE !== "0",
+  /** TTSR stream-interrupting rules (A/B control, default ON — set to "0" to disable). */
+  ttsr: (): boolean => process.env.TSFORGE_TTSR !== "0",
+  /** Instant per-file type diagnostics appended to edit/create tool results
+   *  (A/B control, default ON — set to "0" to disable). */
+  lspWriteFeedback: (): boolean =>
+    process.env.TSFORGE_LSP_WRITE_FEEDBACK !== "0",
+};

package/src/config/index.ts

@@ -0,0 +1,8 @@
+export * from "./config.constants";
+export { flags } from "./flags";
+export {
+  loadTsforgeConfig,
+  resolveActivePacks,
+  normalizeRuleOverrides,
+  type ITsforgeProjectConfig,
+} from "./tsforge-config";

package/src/config/tsforge-config.ts

@@ -0,0 +1,301 @@
+import { join } from "node:path";
+import { isRecord } from "../lib/guards";
+import { PACK_REGISTRY } from "../stack-detection";
+
+/**
+ * User-defined configuration from tsforge.config.json
+ * Allows users to tune the opinionated guardrails — override detected packs,
+ * include/exclude packs, and tune rule severities (eslint packs + meta-rules).
+ */
+export interface ITsforgeProjectConfig {
+  /** Force-enable a stack by name (skip detection heuristics, force-add its packs). */
+  readonly stack?: string;
+
+  /** Pack include/exclude — applied AFTER detection. */
+  readonly packs?: {
+    readonly include?: readonly string[];
+    readonly exclude?: readonly string[];
+  };
+
+  /**
+   * ESLint rule + meta-rule severity overrides.
+   * Keys: bare rule name ("timestamp-must-specify-mode") or tsforge-prefixed ("tsforge/timestamp-must-specify-mode").
+   * Values: "error" | "warn" | "off" (off silences the rule).
+   */
+  readonly rules?: Readonly<Record<string, "error" | "warn" | "off">>;
+}
+
+function warnConfig(msg: string): void {
+  process.stderr.write(`${msg}\n`);
+}
+
+function warnInvalidStackType(stackValue: unknown): void {
+  const msg = `tsforge.config.json: "stack" must be a string, got ${typeof stackValue}`;
+
+  warnConfig(msg);
+}
+
+function warnInvalidPacksType(packsValue: unknown): void {
+  const msg = `tsforge.config.json: "packs" must be an object, got ${typeof packsValue}`;
+
+  warnConfig(msg);
+}
+
+function warnInvalidPacksInclude(): void {
+  warnConfig("tsforge.config.json: packs.include must be an array of strings");
+}
+
+function warnInvalidPacksExclude(): void {
+  warnConfig("tsforge.config.json: packs.exclude must be an array of strings");
+}
+
+function warnInvalidRulesType(rulesValue: unknown): void {
+  const msg = `tsforge.config.json: "rules" must be an object, got ${typeof rulesValue}`;
+
+  warnConfig(msg);
+}
+
+function warnInvalidRuleSeverity(key: string, value: unknown): void {
+  const msg = `tsforge.config.json: rule "${key}" severity must be "error", "warn", or "off", got "${String(value)}"`;
+
+  warnConfig(msg);
+}
+
+function warnInvalidJsonRoot(rootValue: unknown): void {
+  const msg = `tsforge.config.json: expected object root, got ${typeof rootValue}`;
+
+  warnConfig(msg);
+}
+
+function warnInvalidJson(msg: string | undefined): void {
+  const displayMsg =
+    msg !== undefined && msg.length > 0 ? msg : "parsing failed";
+
+  warnConfig(`tsforge.config.json: invalid JSON — ${displayMsg}`);
+}
+
+function warnReadError(msg: string): void {
+  warnConfig(`tsforge.config.json: read error — ${msg}`);
+}
+
+function warnUnknownPackInInclude(packId: string): void {
+  const msg = `tsforge.config.json: unknown pack in packs.include: "${packId}" (will be ignored)`;
+
+  warnConfig(msg);
+}
+
+/** Validate and extract stack field. */
+function validateStack(parsed: unknown): string | undefined {
+  if (typeof parsed === "string") {
+    return parsed;
+  }
+
+  warnInvalidStackType(parsed);
+
+  return undefined;
+}
+
+/** Validate and extract packs field. */
+function validatePacks(
+  parsed: unknown
+): { include?: readonly string[]; exclude?: readonly string[] } | undefined {
+  if (!isRecord(parsed)) {
+    warnInvalidPacksType(parsed);
+
+    return undefined;
+  }
+
+  const packFields: {
+    include?: readonly string[];
+    exclude?: readonly string[];
+  } = {};
+
+  if (parsed.include !== undefined) {
+    if (
+      Array.isArray(parsed.include) &&
+      parsed.include.every((x) => typeof x === "string")
+    ) {
+      packFields.include = parsed.include;
+    } else {
+      warnInvalidPacksInclude();
+    }
+  }
+
+  if (parsed.exclude !== undefined) {
+    if (
+      Array.isArray(parsed.exclude) &&
+      parsed.exclude.every((x) => typeof x === "string")
+    ) {
+      packFields.exclude = parsed.exclude;
+    } else {
+      warnInvalidPacksExclude();
+    }
+  }
+
+  return Object.keys(packFields).length > 0 ? packFields : undefined;
+}
+
+/** Validate and extract rules field. */
+function validateRules(
+  parsed: unknown
+): Record<string, "error" | "warn" | "off"> | undefined {
+  if (!isRecord(parsed)) {
+    warnInvalidRulesType(parsed);
+
+    return undefined;
+  }
+
+  const rulesFields: Record<string, "error" | "warn" | "off"> = {};
+
+  for (const [key, value] of Object.entries(parsed)) {
+    if (value === "error" || value === "warn" || value === "off") {
+      rulesFields[key] = value;
+    } else {
+      warnInvalidRuleSeverity(key, value);
+    }
+  }
+
+  return Object.keys(rulesFields).length > 0 ? rulesFields : undefined;
+}
+
+/** Load tsforge.config.json from cwd, defaulting to empty config on missing/invalid files. */
+export async function loadTsforgeConfig(
+  cwd: string
+): Promise<ITsforgeProjectConfig> {
+  const configPath = join(cwd, "tsforge.config.json");
+  const file = Bun.file(configPath);
+
+  const exists = await file.exists();
+
+  if (!exists) {
+    return {};
+  }
+
+  try {
+    const text = await file.text();
+    const parsed: unknown = JSON.parse(text);
+
+    if (!isRecord(parsed)) {
+      warnInvalidJsonRoot(parsed);
+
+      return {};
+    }
+
+    const configFields: {
+      stack?: string;
+      packs?: { include?: readonly string[]; exclude?: readonly string[] };
+      rules?: Record<string, "error" | "warn" | "off">;
+    } = {};
+
+    if (parsed.stack !== undefined) {
+      const stack = validateStack(parsed.stack);
+
+      if (stack !== undefined) {
+        configFields.stack = stack;
+      }
+    }
+
+    if (parsed.packs !== undefined) {
+      const packs = validatePacks(parsed.packs);
+
+      if (packs !== undefined) {
+        configFields.packs = packs;
+      }
+    }
+
+    if (parsed.rules !== undefined) {
+      const rules = validateRules(parsed.rules);
+
+      if (rules !== undefined) {
+        configFields.rules = rules;
+      }
+    }
+
+    return configFields;
+  } catch (err) {
+    if (err instanceof SyntaxError) {
+      const firstLine = err.message.split("\n")[0];
+
+      warnInvalidJson(firstLine);
+    } else {
+      const msg = err instanceof Error ? err.message : "unknown error";
+
+      warnReadError(msg);
+    }
+
+    return {};
+  }
+}
+
+/**
+ * Resolve the active packs after applying config overrides.
+ * Rules:
+ *  1. Start with detected packs (from stack detection)
+ *  2. If config.stack is set, force-add its packs (as if detected)
+ *  3. Apply packs.include (add unknown packs with warning)
+ *  4. Apply packs.exclude (remove known and unknown packs silently)
+ *  5. Return deduplicated pack list
+ */
+export function resolveActivePacks(
+  detectedPacks: readonly string[],
+  config: ITsforgeProjectConfig
+): readonly string[] {
+  const packs = new Set(detectedPacks);
+
+  // Force-add packs for config.stack if set
+  if (config.stack !== undefined && config.stack.length > 0) {
+    packs.add(config.stack);
+  }
+
+  // Include: add packs (unknown ids are kept out of the registry lookup warning only)
+  for (const packId of config.packs?.include ?? []) {
+    if (packId.length === 0) {
+      continue;
+    }
+
+    if (!(packId in PACK_REGISTRY)) {
+      warnUnknownPackInInclude(packId);
+    }
+
+    packs.add(packId);
+  }
+
+  // Exclude: remove packs
+  for (const packId of config.packs?.exclude ?? []) {
+    packs.delete(packId);
+  }
+
+  // Return as sorted array for determinism
+  return Array.from(packs).sort();
+}
+
+/**
+ * Normalize rule name keys: accept both bare ("timestamp-must-specify-mode")
+ * and tsforge-prefixed ("tsforge/timestamp-must-specify-mode").
+ * Returns a map keyed by the BARE rule name.
+ */
+function isSeverityOverride(value: unknown): value is "error" | "warn" | "off" {
+  return value === "error" || value === "warn" || value === "off";
+}
+
+export function normalizeRuleOverrides(
+  config: ITsforgeProjectConfig
+): Record<string, "error" | "warn" | "off"> {
+  const normalized: Record<string, "error" | "warn" | "off"> = {};
+
+  for (const [key, severity] of Object.entries(config.rules ?? {})) {
+    // Runtime data can violate the declared union (hand-built configs in tests,
+    // partially validated JSON) — re-check before trusting it.
+    if (!isSeverityOverride(severity)) {
+      continue;
+    }
+
+    const bareKey = key.startsWith("tsforge/") ? key.slice(8) : key;
+
+    if (bareKey.length > 0) {
+      normalized[bareKey] = severity;
+    }
+  }
+
+  return normalized;
+}

package/src/constitution/baseline.ts

@@ -0,0 +1,257 @@
+import { join } from "node:path";
+
+/**
+ * The baseline constitution — the deterministic gate floor tsforge brings to an
+ * under-gated TypeScript repo so "correct" has a meaning even where the repo
+ * ships none. Mirrors tsforge's OWN gate (strict `tsc` + the boringstack-derived
+ * eslint house rules + prettier), so a target fails the same way tsforge does.
+ *
+ * Bringing it is NON-DESTRUCTIVE: a repo's own config for a tool is authority,
+ * and we only write a file when nothing equivalent exists. We never install
+ * dependencies — `dependencies` lists what the written configs need so the
+ * caller can ensure them separately.
+ */
+
+const TSCONFIG = `{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "noEmit": true,
+
+    "strict": true,
+    "useUnknownInCatchVariables": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noImplicitReturns": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist", "scratch"]
+}
+`;
+
+const PRETTIER = `{
+  "semi": true,
+  "trailingComma": "es5",
+  "singleQuote": false,
+  "printWidth": 80,
+  "tabWidth": 2
+}
+`;
+
+const ESLINT = `import pluginJs from "@eslint/js";
+import tseslint from "typescript-eslint";
+import configPrettier from "eslint-config-prettier";
+import pluginPrettier from "eslint-plugin-prettier";
+
+// Brought by tsforge: the general TypeScript quality rules (type-safety, async
+// correctness, strict-boolean, I-prefixed interfaces, no-enum, prettier). Every
+// rule is \`error\` — local green == CI green. Delete or relax in your own config.
+export default tseslint.config(
+  { ignores: ["**/node_modules/**", "**/dist/**"] },
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    extends: [
+      pluginJs.configs.recommended,
+      ...tseslint.configs.strictTypeChecked,
+      ...tseslint.configs.stylisticTypeChecked,
+      configPrettier,
+    ],
+    languageOptions: {
+      parser: tseslint.parser,
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: import.meta.dirname,
+      },
+    },
+    plugins: {
+      "@typescript-eslint": tseslint.plugin,
+      prettier: pluginPrettier,
+    },
+    rules: {
+      "prettier/prettier": "error",
+
+      // Idiomatic-output rules promoted to the GATE: over-annotation and
+      // string concatenation become deterministic errors, not reviewer notes.
+      "@typescript-eslint/no-inferrable-types": "error",
+      "prefer-template": "error",
+
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-non-null-assertion": "error",
+      "@typescript-eslint/consistent-type-assertions": [
+        "error",
+        { assertionStyle: "never" },
+      ],
+
+      "@typescript-eslint/no-floating-promises": "error",
+      "@typescript-eslint/no-misused-promises": "error",
+
+      "@typescript-eslint/strict-boolean-expressions": [
+        "error",
+        {
+          allowString: false,
+          allowNumber: false,
+          allowNullableObject: true,
+          allowNullableBoolean: false,
+          allowNullableString: false,
+          allowNullableNumber: false,
+          allowAny: false,
+        },
+      ],
+
+      "@typescript-eslint/naming-convention": [
+        "error",
+        { selector: "interface", format: ["PascalCase"], prefix: ["I"] },
+        { selector: "typeAlias", format: ["PascalCase"] },
+        { selector: "typeParameter", format: ["PascalCase"] },
+        {
+          selector: "variable",
+          format: ["camelCase", "UPPER_CASE", "PascalCase"],
+          leadingUnderscore: "allow",
+        },
+        { selector: "function", format: ["camelCase", "PascalCase"] },
+        { selector: ["objectLiteralProperty", "typeProperty"], format: null },
+      ],
+
+      eqeqeq: ["error", "always"],
+      curly: ["error", "all"],
+      "no-var": "error",
+      "prefer-const": "error",
+      "no-restricted-syntax": [
+        "error",
+        {
+          selector: "TSEnumDeclaration",
+          message: "Use 'as const' object literals instead of enums.",
+        },
+      ],
+    },
+  }
+);
+`;
+
+interface IBaselineFile {
+  /** The file we write when nothing equivalent is present. */
+  path: string;
+  /** Any of these existing means the repo already has this tool's config. */
+  satisfiedBy: string[];
+  content: string;
+}
+
+const FILES: IBaselineFile[] = [
+  { path: "tsconfig.json", satisfiedBy: ["tsconfig.json"], content: TSCONFIG },
+  {
+    path: "eslint.config.js",
+    satisfiedBy: [
+      "eslint.config.js",
+      "eslint.config.mjs",
+      "eslint.config.cjs",
+      ".eslintrc",
+      ".eslintrc.js",
+      ".eslintrc.cjs",
+      ".eslintrc.json",
+    ],
+    content: ESLINT,
+  },
+  {
+    path: ".prettierrc.json",
+    satisfiedBy: [
+      ".prettierrc",
+      ".prettierrc.json",
+      ".prettierrc.js",
+      ".prettierrc.cjs",
+      "prettier.config.js",
+      "prettier.config.mjs",
+    ],
+    content: PRETTIER,
+  },
+];
+
+/** What the brought configs need installed (we never install them ourselves). */
+const DEPENDENCIES = [
+  "typescript",
+  "@eslint/js",
+  "eslint",
+  "typescript-eslint",
+  "eslint-config-prettier",
+  "eslint-plugin-prettier",
+  "prettier",
+];
+
+export interface IConstitutionState {
+  tsconfig: boolean;
+  eslint: boolean;
+  prettier: boolean;
+}
+
+export interface IBroughtConstitution {
+  /** Config files written (were absent). */
+  written: string[];
+  /** Config files left alone (the repo already had one). */
+  skipped: string[];
+  /** npm dependencies the written configs require. */
+  dependencies: string[];
+  /** The gate command that runs the constitution. */
+  verify: string;
+}
+
+export interface IBringOptions {
+  /** Test command appended to the gate (default `bun test`). */
+  testCommand?: string;
+}
+
+/** Report which parts of the constitution the repo already has — writes nothing. */
+export async function analyzeConstitution(
+  cwd: string
+): Promise<IConstitutionState> {
+  return {
+    tsconfig: await anyExists(cwd, FILES[0]?.satisfiedBy ?? []),
+    eslint: await anyExists(cwd, FILES[1]?.satisfiedBy ?? []),
+    prettier: await anyExists(cwd, FILES[2]?.satisfiedBy ?? []),
+  };
+}
+
+/** Materialize the missing parts of the gate floor into `cwd`, non-destructively. */
+export async function bringConstitution(
+  cwd: string,
+  opts: IBringOptions = {}
+): Promise<IBroughtConstitution> {
+  const written: string[] = [];
+  const skipped: string[] = [];
+
+  for (const file of FILES) {
+    if (await anyExists(cwd, file.satisfiedBy)) {
+      skipped.push(file.path);
+      continue;
+    }
+
+    await Bun.write(join(cwd, file.path), file.content);
+    written.push(file.path);
+  }
+
+  const testCommand = opts.testCommand ?? "bun test";
+  const verify = [
+    "tsc --noEmit -p tsconfig.json",
+    "eslint .",
+    'prettier --check "**/*.{ts,tsx}"',
+    testCommand,
+  ].join(" && ");
+
+  return { written, skipped, dependencies: DEPENDENCIES, verify };
+}
+
+async function anyExists(cwd: string, names: string[]): Promise<boolean> {
+  for (const name of names) {
+    if (await Bun.file(join(cwd, name)).exists()) {
+      return true;
+    }
+  }
+
+  return false;
+}