@sha3/code 1.0.0

package/bin/code-standards.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+import { parseInitArgs, parseProfileArgs, parseRefactorArgs, parseVerifyArgs, printUsage } from "../lib/cli/parse-args.mjs";
+import { runInit } from "../lib/cli/run-init.mjs";
+import { runProfile } from "../lib/cli/run-profile.mjs";
+import { runRefactor } from "../lib/cli/run-refactor.mjs";
+import { runVerify } from "../lib/cli/run-verify.mjs";
+
+async function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.length === 0 || argv.includes("-h") || argv.includes("--help")) {
+    printUsage();
+    process.exit(0);
+  }
+
+  const [command, ...rest] = argv;
+
+  try {
+    if (command === "init") {
+      await runInit(parseInitArgs(rest));
+      return;
+    }
+
+    if (command === "refactor") {
+      await runRefactor(parseRefactorArgs(rest));
+      return;
+    }
+
+    if (command === "profile") {
+      await runProfile(parseProfileArgs(rest));
+      return;
+    }
+
+    if (command === "verify") {
+      await runVerify(parseVerifyArgs(rest));
+      return;
+    }
+
+    throw new Error(`Unknown command: ${command}`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+}
+
+main();

package/biome.json

@@ -0,0 +1,37 @@
+{
+  "files": {
+    "ignoreUnknown": true,
+    "ignore": [".code-standards", "dist"]
+  },
+  "formatter": {
+    "enabled": true,
+    "indentStyle": "space",
+    "indentWidth": 2,
+    "lineWidth": 160
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "correctness": {
+        "noUnusedFunctionParameters": "error",
+        "noUnusedImports": "error",
+        "noUnusedPrivateClassMembers": "error",
+        "noUnusedVariables": "error"
+      }
+    }
+  },
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double",
+      "semicolons": "always",
+      "arrowParentheses": "always",
+      "bracketSpacing": true
+    }
+  },
+  "json": {
+    "formatter": {
+      "enabled": true
+    }
+  }
+}

package/index.mjs

@@ -0,0 +1,11 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const rootDir = path.dirname(fileURLToPath(import.meta.url));
+
+export const tsconfigPaths = {
+  base: path.join(rootDir, "tsconfig", "base.json"),
+  nodeLib: path.join(rootDir, "tsconfig", "node-lib.json"),
+  nodeService: path.join(rootDir, "tsconfig", "node-service.json"),
+};
+
+export const biomeConfigPath = path.join(rootDir, "biome.json");

package/lib/cli/parse-args.mjs

@@ -0,0 +1,416 @@
+import { TEMPLATE_NAMES } from "../constants.mjs";
+
+export function printUsage() {
+  console.log(`Usage:
+  code-standards <command> [options]
+
+Commands:
+  init                  Initialize a project in the current directory
+  refactor              Snapshot the current repo and rebuild it from the active scaffold
+  profile               Create or update the AI style profile
+  verify                Validate deterministic standards in a project
+
+Init options:
+  --template <node-lib|node-service>
+  --package-name <name>
+  --repository-url <url>
+  --yes
+  --no-install
+  --force
+  --with-ai-adapters
+  --no-ai-adapters
+  --profile <path>
+
+Refactor options:
+  --template <node-lib|node-service>
+  --package-name <name>
+  --repository-url <url>
+  --profile <path>
+  --with-ai-adapters
+  --no-ai-adapters
+  --install
+  --yes
+  --force
+
+Verify options:
+  --report <text|json>
+  --only <rule-id[,rule-id...]>
+  --files <path[,path...]>
+  --explain <rule-id>
+  --strict
+  --changed-against <ref>
+  --staged
+  --all-files
+
+Profile options:
+  --profile <path>
+  --non-interactive
+  --force-profile
+
+Global:
+  -h, --help`);
+}
+
+export function parseInitArgs(argv) {
+  const options = {
+    template: undefined,
+    packageName: undefined,
+    repositoryUrl: undefined,
+    yes: false,
+    install: true,
+    force: false,
+    withAiAdapters: true,
+    profilePath: undefined,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (!token.startsWith("-")) {
+      throw new Error(`Positional project names are not supported: ${token}. Run init from your target directory.`);
+    }
+
+    if (token === "--template") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --template");
+      }
+      if (!TEMPLATE_NAMES.includes(value)) {
+        throw new Error(`Invalid template: ${value}`);
+      }
+      options.template = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--target") {
+      throw new Error("--target is not supported. Run init from your target directory.");
+    }
+
+    if (token === "--profile") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --profile");
+      }
+      options.profilePath = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--package-name") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --package-name");
+      }
+      options.packageName = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--repository-url") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --repository-url");
+      }
+      options.repositoryUrl = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--yes") {
+      options.yes = true;
+      continue;
+    }
+
+    if (token === "--no-install") {
+      options.install = false;
+      continue;
+    }
+
+    if (token === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    if (token === "--with-ai-adapters") {
+      options.withAiAdapters = true;
+      continue;
+    }
+
+    if (token === "--no-ai-adapters") {
+      options.withAiAdapters = false;
+      continue;
+    }
+
+    if (token === "-h" || token === "--help") {
+      options.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${token}`);
+  }
+
+  return options;
+}
+
+export function parseRefactorArgs(argv) {
+  const options = {
+    template: undefined,
+    packageName: undefined,
+    repositoryUrl: undefined,
+    profilePath: undefined,
+    withAiAdapters: true,
+    install: false,
+    yes: false,
+    force: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (!token.startsWith("-")) {
+      throw new Error(`Positional arguments are not supported for refactor: ${token}.`);
+    }
+
+    if (token === "--template") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --template");
+      }
+      if (!TEMPLATE_NAMES.includes(value)) {
+        throw new Error(`Invalid template: ${value}`);
+      }
+      options.template = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--package-name") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --package-name");
+      }
+      options.packageName = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--repository-url") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --repository-url");
+      }
+      options.repositoryUrl = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--profile") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --profile");
+      }
+      options.profilePath = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--with-ai-adapters") {
+      options.withAiAdapters = true;
+      continue;
+    }
+
+    if (token === "--no-ai-adapters") {
+      options.withAiAdapters = false;
+      continue;
+    }
+
+    if (token === "--install") {
+      options.install = true;
+      continue;
+    }
+
+    if (token === "--yes") {
+      options.yes = true;
+      continue;
+    }
+
+    if (token === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    if (token === "-h" || token === "--help") {
+      options.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${token}`);
+  }
+
+  return options;
+}
+
+export function parseProfileArgs(argv) {
+  const options = { profilePath: undefined, nonInteractive: false, forceProfile: false, help: false };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === "--profile") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --profile");
+      }
+      options.profilePath = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--non-interactive") {
+      options.nonInteractive = true;
+      continue;
+    }
+
+    if (token === "--force-profile") {
+      options.forceProfile = true;
+      continue;
+    }
+
+    if (token === "-h" || token === "--help") {
+      options.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${token}`);
+  }
+
+  return options;
+}
+
+export function parseVerifyArgs(argv) {
+  const options = {
+    report: "text",
+    onlyRuleIds: undefined,
+    files: undefined,
+    explainRuleId: undefined,
+    strict: false,
+    changedAgainst: undefined,
+    staged: false,
+    allFiles: false,
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+
+    if (token === "--report") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --report");
+      }
+      if (value !== "text" && value !== "json") {
+        throw new Error(`Invalid value for --report: ${value}`);
+      }
+      options.report = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--only") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --only");
+      }
+      const onlyRuleIds = [
+        ...new Set(
+          value
+            .split(",")
+            .map((ruleId) => ruleId.trim())
+            .filter((ruleId) => ruleId.length > 0),
+        ),
+      ];
+      if (onlyRuleIds.length === 0) {
+        throw new Error("--only requires at least one rule id");
+      }
+      options.onlyRuleIds = onlyRuleIds;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--files") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --files");
+      }
+      const files = [
+        ...new Set(
+          value
+            .split(",")
+            .map((filePath) => filePath.trim())
+            .filter((filePath) => filePath.length > 0),
+        ),
+      ];
+      if (files.length === 0) {
+        throw new Error("--files requires at least one path");
+      }
+      options.files = files;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--explain") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --explain");
+      }
+      options.explainRuleId = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--changed-against") {
+      const value = argv[i + 1];
+      if (!value || value.startsWith("-")) {
+        throw new Error("Missing value for --changed-against");
+      }
+      options.changedAgainst = value;
+      i += 1;
+      continue;
+    }
+
+    if (token === "--strict") {
+      options.strict = true;
+      continue;
+    }
+
+    if (token === "--staged") {
+      options.staged = true;
+      continue;
+    }
+
+    if (token === "--all-files") {
+      options.allFiles = true;
+      continue;
+    }
+
+    if (token === "-h" || token === "--help") {
+      options.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${token}`);
+  }
+
+  if (options.explainRuleId && (options.onlyRuleIds || options.files || options.report !== "text")) {
+    throw new Error("--explain cannot be combined with --only, --files, or --report");
+  }
+
+  if (options.staged && options.allFiles) {
+    throw new Error("--staged cannot be combined with --all-files");
+  }
+
+  return options;
+}

package/lib/cli/post-run-guidance.mjs

@@ -0,0 +1,43 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+
+function printIndentedLines(lines) {
+  for (const line of lines) {
+    console.log(`  ${line}`);
+  }
+}
+
+export function printInitGuidance(targetPath) {
+  console.log(`Project created at ${targetPath}`);
+  console.log("Guided next steps:");
+  printIndentedLines([
+    "1. Open PROMPT.md and complete the User Request section.",
+    "2. Paste only PROMPT.md into the LLM.",
+    "3. The LLM must read the phase prompts itself, execute the workflow end to end, run npm run check, and update SCAFFOLD-FEEDBACK.md.",
+    "4. Remember that Biome ignores managed contract files by default, and single-return stays strict outside src/http/.",
+  ]);
+}
+
+export async function printRefactorGuidance(targetPath) {
+  const promptPath = path.join(targetPath, "PROMPT.md");
+
+  console.log(`Project refactored at ${targetPath}`);
+  console.log("Legacy code was moved into .code-standards/refactor-source/latest/ for reference.");
+  console.log("The snapshot is legacy reference only. Do not restore managed files or toolchain files from it.");
+  console.log("The LLM MUST analyze the legacy code and then rebuild on the fresh scaffold. It MUST NOT copy the legacy structure as-is.");
+  console.log("No lint, format, or check pass was run against the intermediate refactor state.");
+  console.log("Final npm run check is deferred until after the LLM rewrites src/ and test/.");
+  console.log("The user should only fill PROMPT.md; the LLM must load and follow the phase prompts by itself.");
+
+  try {
+    const prompt = await readFile(promptPath, "utf8");
+
+    console.log("Start from this single LLM entry file:");
+    console.log("");
+    console.log("----- BEGIN PROMPT CHECKLIST -----");
+    console.log(prompt.trimEnd());
+    console.log("----- END PROMPT CHECKLIST -----");
+  } catch {
+    console.log(`Refactor prompt written to ${promptPath}`);
+  }
+}

package/lib/cli/run-init.mjs

@@ -0,0 +1,123 @@
+import path from "node:path";
+
+import { TEMPLATE_NAMES } from "../constants.mjs";
+import { loadProfileSchema, readPackageVersion, resolvePackageRoot } from "../paths.mjs";
+import { resolveProfileForInit } from "../profile.mjs";
+import { generateAiInstructions } from "../project/ai-instructions.mjs";
+import { ensureBiomeIgnore } from "../project/biome-ignore.mjs";
+import { applyPackageCoordinates, readProjectPackageJson, updateCodeStandardsMetadata, writeProjectPackageJson } from "../project/package-metadata.mjs";
+import { validateInitResources } from "../project/template-resolution.mjs";
+import { copyTemplateDirectory, ensureTargetReady, formatFilesWithBiome, runCommand } from "../utils/fs.mjs";
+import { promptYesNo, withReadline } from "../utils/prompts.mjs";
+import { defaultPackageNameForProject, defaultRepositoryUrlForPackage, normalizePackageName, normalizeRepositoryUrl } from "../utils/text.mjs";
+import { printInitGuidance } from "./post-run-guidance.mjs";
+
+async function promptForMissing(options, targetPath) {
+  return withReadline(async (rl) => {
+    const resolved = { ...options };
+    const inferredProjectName = path.basename(targetPath);
+    const projectName = inferredProjectName && inferredProjectName !== path.sep ? inferredProjectName : "my-project";
+    const defaultPackageName = defaultPackageNameForProject(projectName);
+
+    if (!resolved.template) {
+      const templateAnswer = await rl.question("Choose template (node-lib/node-service) [node-lib]: ");
+      const normalized = templateAnswer.trim() || "node-lib";
+
+      if (!TEMPLATE_NAMES.includes(normalized)) {
+        throw new Error(`Invalid template: ${normalized}`);
+      }
+
+      resolved.template = normalized;
+    }
+
+    if (!resolved.packageName) {
+      const packageAnswer = await rl.question(`npm package name [${defaultPackageName}]: `);
+      resolved.packageName = packageAnswer.trim() || defaultPackageName;
+    }
+
+    if (!resolved.repositoryUrl) {
+      const defaultRepositoryUrl = defaultRepositoryUrlForPackage(resolved.packageName);
+      const repositoryAnswer = await rl.question(`GitHub repository URL [${defaultRepositoryUrl}]: `);
+      resolved.repositoryUrl = repositoryAnswer.trim() || defaultRepositoryUrl;
+    }
+
+    if (options.install) {
+      const shouldInstall = await promptYesNo(rl, "Install dependencies now?", true);
+      resolved.install = shouldInstall;
+    }
+
+    return resolved;
+  });
+}
+
+export async function runInit(rawOptions) {
+  if (rawOptions.help) {
+    const { printUsage } = await import("./parse-args.mjs");
+    printUsage();
+    return;
+  }
+
+  let options = { ...rawOptions };
+  const targetPath = path.resolve(process.cwd());
+  const inferredProjectName = path.basename(targetPath);
+  const projectName = inferredProjectName && inferredProjectName !== path.sep ? inferredProjectName : "my-project";
+  const defaultPackageName = defaultPackageNameForProject(projectName);
+
+  if (options.yes || !process.stdin.isTTY) {
+    options.template ??= "node-lib";
+    options.packageName ??= defaultPackageName;
+    options.repositoryUrl ??= defaultRepositoryUrlForPackage(options.packageName);
+  } else {
+    options = await promptForMissing(options, targetPath);
+  }
+
+  const template = options.template ?? "node-lib";
+
+  if (!TEMPLATE_NAMES.includes(template)) {
+    throw new Error(`Invalid template: ${template}`);
+  }
+
+  const packageRoot = resolvePackageRoot();
+  const packageVersion = await readPackageVersion(packageRoot);
+  const schema = await loadProfileSchema(packageRoot);
+  const profileResolution = await resolveProfileForInit(packageRoot, targetPath, options, schema);
+  const packageName = normalizePackageName(options.packageName, projectName);
+  const repositoryUrl = normalizeRepositoryUrl(options.repositoryUrl, packageName);
+
+  await ensureTargetReady(targetPath, options.force);
+
+  const { templateDir } = await validateInitResources(packageRoot, template);
+  const tokens = { projectName, packageName, packageVersion, year: String(new Date().getFullYear()) };
+
+  await copyTemplateDirectory(templateDir, targetPath, tokens);
+
+  const contract = await generateAiInstructions({
+    packageRoot,
+    packageVersion,
+    targetDir: targetPath,
+    tokens,
+    profile: profileResolution.profile,
+    template,
+    withAiAdapters: options.withAiAdapters,
+    workflow: "init",
+  });
+  await ensureBiomeIgnore(targetPath, contract.managedFiles);
+
+  if (options.install) {
+    console.log("Installing dependencies...");
+    await runCommand("npm", ["install"], targetPath);
+  }
+
+  const { packageJsonPath, packageJson } = await readProjectPackageJson(targetPath);
+  const packageWithCoordinates = applyPackageCoordinates(packageJson, packageName, repositoryUrl);
+  const packageWithMetadata = updateCodeStandardsMetadata(packageWithCoordinates, {
+    template,
+    profilePath: profileResolution.profilePathForMetadata,
+    withAiAdapters: options.withAiAdapters,
+    lastRefactorWith: packageVersion,
+  });
+  await writeProjectPackageJson(packageJsonPath, packageWithMetadata);
+  await formatFilesWithBiome(packageRoot, targetPath, ["package.json", "ai/contract.json"]);
+
+  printInitGuidance(targetPath);
+}