@sha3/code-standards 0.1.4 → 0.1.6

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# @sha3/code-standards
+# 📏 @sha3/code-standards
 
 **Scaffold TypeScript projects + enforce how AI writes code.**
 
@@ -21,6 +21,12 @@ If you just want to start now:
 npx @sha3/code-standards init --template node-service --yes
 ```
 
+If your project was already scaffolded and you updated this package:
+
+```bash
+npx @sha3/code-standards refresh
+```
+
 Then in your AI chat, paste this:
 
 ```txt
@@ -111,8 +117,12 @@ After `init`, your new repo contains:
 - `ai/examples/rules/*.ts` (good/bad examples per rule)
 - `ai/examples/demo/src/*` (feature-folder demo with classes and section blocks)
 - `src/config.ts` for centralized hardcoded configuration values
+- `README.md` generated with an icon emoji in the main header
 - `.gitignore` preconfigured for Node/TypeScript output
 - lint/format/typecheck/test-ready project template
+- `package.json.codeStandards` metadata used by `refresh` (`template`, `profilePath`, `withAiAdapters`, `lastRefreshWith`)
+
+`config.ts` convention: export a single default object and import it as `import CONFIG from "./config.js"`.
 
 That means the next step is **not** configuring tools. The next step is telling your assistant to obey `AGENTS.md` before coding.
 
@@ -270,6 +280,22 @@ npm run check
 
 Then use the prompts above in your AI tool.
 
+### 4) Sync updates from `@sha3/code-standards`
+
+Run this inside an already scaffolded project:
+
+```bash
+npx @sha3/code-standards refresh
+```
+
+`refresh` default behavior:
+
+- scope `Managed + AI` (template files + `AGENTS.md` + `ai/*` + `ai/examples/*`)
+- overwrite conflicts
+- auto-detect template (or force with `--template`)
+- selective merge for `package.json` (managed scripts/devDependencies updated, custom keys preserved)
+- no dependency install unless `--install`
+
 ---
 
 ## CLI Reference
@@ -279,6 +305,8 @@ code-standards <command> [options]
 
 Commands:
   init                  Initialize a project in the current directory
+  refresh               Re-apply managed standards files and AI instructions
+  update                Alias of refresh
   profile               Create or update the AI style profile
 ```
 
@@ -295,6 +323,18 @@ An existing `.git/` directory is allowed without `--force`.
 - `--no-ai-adapters`
 - `--profile <path>`
 
+### `refresh` options
+
+`refresh` always uses the current working directory as target.
+
+- `--template <node-lib|node-service>`
+- `--profile <path>`
+- `--with-ai-adapters`
+- `--no-ai-adapters`
+- `--dry-run`
+- `--install`
+- `--yes`
+
 ### `profile` options
 
 - `--profile <path>`

package/bin/code-standards.mjs

@@ -10,6 +10,12 @@ import { fileURLToPath } from "node:url";
 import Ajv2020 from "ajv/dist/2020.js";
 
 const TEMPLATE_NAMES = ["node-lib", "node-service"];
+const CODE_STANDARDS_METADATA_KEY = "codeStandards";
+const NODE_LIB_REFRESH_SIGNATURE = {
+  main: "dist/index.js",
+  types: "dist/index.d.ts"
+};
+const NODE_SERVICE_START_SIGNATURE = "node --import tsx src/index.ts";
 const PROFILE_KEY_ORDER = [
   "version",
   "paradigm",
@@ -165,6 +171,8 @@ function printUsage() {
 
 Commands:
   init                  Initialize a project in the current directory
+  refresh               Re-apply managed standards files and AI instructions
+  update                Alias of refresh
   profile               Create or update the AI style profile
 
 Init options:
@@ -176,6 +184,15 @@ Init options:
   --no-ai-adapters
   --profile <path>
 
+Refresh options:
+  --template <node-lib|node-service>
+  --profile <path>
+  --with-ai-adapters
+  --no-ai-adapters
+  --dry-run
+  --install
+  --yes
+
 Profile options:
   --profile <path>
   --non-interactive
@@ -271,6 +288,88 @@ function parseInitArgs(argv) {
   return options;
 }
 
+function parseRefreshArgs(argv) {
+  const options = {
+    template: undefined,
+    profilePath: undefined,
+    withAiAdapters: true,
+    dryRun: false,
+    install: false,
+    yes: 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 refresh: ${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 === "--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 === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (token === "--install") {
+      options.install = true;
+      continue;
+    }
+
+    if (token === "--yes") {
+      options.yes = true;
+      continue;
+    }
+
+    if (token === "-h" || token === "--help") {
+      options.help = true;
+      continue;
+    }
+
+    throw new Error(`Unknown option: ${token}`);
+  }
+
+  return options;
+}
+
 function parseProfileArgs(argv) {
   const options = {
     profilePath: undefined,
@@ -422,11 +521,198 @@ async function copyTemplateDirectory(sourceDir, targetDir, tokens) {
   }
 }
 
+function asPlainObject(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+
+  return value;
+}
+
+function getRelativeProfilePath(profilePath, targetPath) {
+  if (!profilePath) {
+    return null;
+  }
+
+  const resolvedProfilePath = path.resolve(targetPath, profilePath);
+  const relativePath = path.relative(targetPath, resolvedProfilePath);
+
+  // If the profile is outside the project directory, return null instead of absolute path
+  // to avoid storing machine-specific paths in package.json
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return null;
+  }
+
+  return relativePath;
+}
+
+async function readProjectPackageJson(targetPath) {
+  const packageJsonPath = path.join(targetPath, "package.json");
+
+  if (!(await pathExists(packageJsonPath))) {
+    throw new Error(`package.json was not found in ${targetPath}. Run refresh from the project root.`);
+  }
+
+  return {
+    packageJsonPath,
+    packageJson: await readJsonFile(packageJsonPath)
+  };
+}
+
+async function writeProjectPackageJson(packageJsonPath, packageJson) {
+  await writeJsonFile(packageJsonPath, packageJson);
+}
+
+function updateCodeStandardsMetadata(projectPackageJson, metadataPatch) {
+  const existingMetadata = asPlainObject(projectPackageJson[CODE_STANDARDS_METADATA_KEY]);
+  const nextMetadata = {
+    ...existingMetadata,
+    ...metadataPatch
+  };
+
+  return {
+    ...projectPackageJson,
+    [CODE_STANDARDS_METADATA_KEY]: nextMetadata
+  };
+}
+
+function mergePackageJsonFromTemplate(projectPackageJson, templatePackageJson, templateName) {
+  const mergedPackageJson = { ...projectPackageJson };
+  const templateScripts = asPlainObject(templatePackageJson.scripts);
+  const templateDevDependencies = asPlainObject(templatePackageJson.devDependencies);
+  const mergedScripts = {
+    ...asPlainObject(projectPackageJson.scripts)
+  };
+  const mergedDevDependencies = {
+    ...asPlainObject(projectPackageJson.devDependencies)
+  };
+
+  for (const [scriptName, scriptValue] of Object.entries(templateScripts)) {
+    mergedScripts[scriptName] = scriptValue;
+  }
+
+  for (const [dependencyName, dependencyVersion] of Object.entries(templateDevDependencies)) {
+    mergedDevDependencies[dependencyName] = dependencyVersion;
+  }
+
+  if (Object.keys(mergedScripts).length > 0) {
+    mergedPackageJson.scripts = mergedScripts;
+  }
+
+  if (Object.keys(mergedDevDependencies).length > 0) {
+    mergedPackageJson.devDependencies = mergedDevDependencies;
+  }
+
+  if (typeof templatePackageJson.type === "string") {
+    mergedPackageJson.type = templatePackageJson.type;
+  }
+
+  if (templateName === "node-lib") {
+    if (typeof templatePackageJson.main === "string") {
+      mergedPackageJson.main = templatePackageJson.main;
+    }
+
+    if (typeof templatePackageJson.types === "string") {
+      mergedPackageJson.types = templatePackageJson.types;
+    }
+
+    if (Array.isArray(templatePackageJson.files)) {
+      mergedPackageJson.files = templatePackageJson.files;
+    }
+  }
+
+  return mergedPackageJson;
+}
+
+async function collectTemplateFiles(templateDir, baseDir = templateDir) {
+  const entries = await readdir(templateDir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const sourcePath = path.join(templateDir, entry.name);
+
+    if (entry.isDirectory()) {
+      const nestedFiles = await collectTemplateFiles(sourcePath, baseDir);
+      files.push(...nestedFiles);
+      continue;
+    }
+
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const sourceRelativePath = path.relative(baseDir, sourcePath);
+    const sourceDirectory = path.dirname(sourceRelativePath);
+    const sourceFileName = path.basename(sourceRelativePath);
+    const mappedFileName = mapTemplateFileName(sourceFileName);
+    const targetRelativePath = sourceDirectory === "." ? mappedFileName : path.join(sourceDirectory, mappedFileName);
+
+    files.push({
+      sourcePath,
+      sourceRelativePath,
+      targetRelativePath
+    });
+  }
+
+  return files.sort((left, right) => left.targetRelativePath.localeCompare(right.targetRelativePath));
+}
+
+async function applyManagedFiles(options) {
+  const { templateDir, targetDir, tokens, templateName, projectPackageJson, dryRun } = options;
+  const templateFiles = await collectTemplateFiles(templateDir);
+  const updatedFiles = [];
+  let mergedPackageJson = { ...projectPackageJson };
+
+  for (const templateFile of templateFiles) {
+    if (templateFile.targetRelativePath === "package.json") {
+      const rawTemplatePackageJson = await readFile(templateFile.sourcePath, "utf8");
+      const renderedTemplatePackageJson = replaceTokens(rawTemplatePackageJson, tokens);
+      const templatePackageJson = JSON.parse(renderedTemplatePackageJson);
+      mergedPackageJson = mergePackageJsonFromTemplate(mergedPackageJson, templatePackageJson, templateName);
+      updatedFiles.push("package.json");
+      continue;
+    }
+
+    const raw = await readFile(templateFile.sourcePath, "utf8");
+    const rendered = replaceTokens(raw, tokens);
+    const targetPath = path.join(targetDir, templateFile.targetRelativePath);
+    updatedFiles.push(templateFile.targetRelativePath);
+
+    if (dryRun) {
+      continue;
+    }
+
+    await mkdir(path.dirname(targetPath), { recursive: true });
+    await writeFile(targetPath, rendered, "utf8");
+  }
+
+  if (!dryRun) {
+    const packageJsonPath = path.join(targetDir, "package.json");
+    await writeProjectPackageJson(packageJsonPath, mergedPackageJson);
+  }
+
+  return {
+    updatedFiles,
+    mergedPackageJson
+  };
+}
+
 function resolvePackageRoot() {
   const binPath = fileURLToPath(import.meta.url);
   return path.resolve(path.dirname(binPath), "..");
 }
 
+async function readPackageVersion(packageRoot) {
+  const packageJsonPath = path.join(packageRoot, "package.json");
+  const packageJson = await readJsonFile(packageJsonPath);
+
+  if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+    throw new Error("Package version is missing in the CLI package.json.");
+  }
+
+  return packageJson.version;
+}
+
 function getBundledProfilePath(packageRoot) {
   return path.join(packageRoot, "profiles", "default.profile.json");
 }
@@ -775,7 +1061,25 @@ async function maybeInitializeProfileInteractively(packageRoot, profilePath) {
   console.log(`Profile initialized at ${profilePath}`);
 }
 
-async function resolveProfileForInit(packageRoot, rawOptions, schema) {
+async function resolveBundledOrDefaultProfile(packageRoot, schema) {
+  const bundledProfilePath = getBundledProfilePath(packageRoot);
+  const bundledExists = await pathExists(bundledProfilePath);
+
+  if (bundledExists) {
+    return {
+      profile: await readAndValidateProfile(bundledProfilePath, schema),
+      profilePathForMetadata: null
+    };
+  }
+
+  validateProfile(DEFAULT_PROFILE, schema, "hardcoded defaults");
+  return {
+    profile: normalizeProfile(DEFAULT_PROFILE),
+    profilePathForMetadata: null
+  };
+}
+
+async function resolveProfileForInit(packageRoot, targetPath, rawOptions, schema) {
   const bundledProfilePath = getBundledProfilePath(packageRoot);
 
   if (!rawOptions.profilePath) {
@@ -783,35 +1087,115 @@ async function resolveProfileForInit(packageRoot, rawOptions, schema) {
 
     if (!bundledExists) {
       if (rawOptions.yes) {
-        validateProfile(DEFAULT_PROFILE, schema, "hardcoded defaults");
-        return normalizeProfile(DEFAULT_PROFILE);
+        return resolveBundledOrDefaultProfile(packageRoot, schema);
       }
 
       await writeJsonFile(bundledProfilePath, normalizeProfile(DEFAULT_PROFILE));
     }
 
-    return readAndValidateProfile(bundledProfilePath, schema);
+    return {
+      profile: await readAndValidateProfile(bundledProfilePath, schema),
+      profilePathForMetadata: null
+    };
   }
 
-  const requestedPath = path.resolve(process.cwd(), rawOptions.profilePath);
+  const requestedPath = path.resolve(targetPath, rawOptions.profilePath);
   const requestedExists = await pathExists(requestedPath);
 
   if (!requestedExists) {
     if (rawOptions.yes) {
-      const bundledExists = await pathExists(bundledProfilePath);
+      return resolveBundledOrDefaultProfile(packageRoot, schema);
+    }
 
-      if (bundledExists) {
-        return readAndValidateProfile(bundledProfilePath, schema);
-      }
+    await maybeInitializeProfileInteractively(packageRoot, requestedPath);
+  }
+
+  return {
+    profile: await readAndValidateProfile(requestedPath, schema),
+    profilePathForMetadata: getRelativeProfilePath(requestedPath, targetPath)
+  };
+}
 
-      validateProfile(DEFAULT_PROFILE, schema, "hardcoded defaults");
-      return normalizeProfile(DEFAULT_PROFILE);
+async function resolveTemplateForRefresh(rawOptions, projectPackageJson, targetPath) {
+  if (rawOptions.template) {
+    return rawOptions.template;
+  }
+
+  const metadata = asPlainObject(projectPackageJson[CODE_STANDARDS_METADATA_KEY]);
+
+  if (typeof metadata.template === "string" && TEMPLATE_NAMES.includes(metadata.template)) {
+    return metadata.template;
+  }
+
+  const projectScripts = asPlainObject(projectPackageJson.scripts);
+  const hasNodeLibSignature =
+    (await pathExists(path.join(targetPath, "tsconfig.build.json"))) &&
+    projectPackageJson.main === NODE_LIB_REFRESH_SIGNATURE.main &&
+    projectPackageJson.types === NODE_LIB_REFRESH_SIGNATURE.types;
+
+  if (hasNodeLibSignature) {
+    return "node-lib";
+  }
+
+  const startScript = typeof projectScripts.start === "string" ? projectScripts.start : "";
+
+  if (startScript.includes(NODE_SERVICE_START_SIGNATURE)) {
+    return "node-service";
+  }
+
+  throw new Error("Unable to infer template for refresh. Use --template <node-lib|node-service>.");
+}
+
+async function resolveProfileForRefresh(packageRoot, targetPath, rawOptions, schema, projectMetadata) {
+  let selectedProfilePath;
+
+  if (rawOptions.profilePath) {
+    selectedProfilePath = path.resolve(targetPath, rawOptions.profilePath);
+  } else if (typeof projectMetadata.profilePath === "string" && projectMetadata.profilePath.trim().length > 0) {
+    selectedProfilePath = path.resolve(targetPath, projectMetadata.profilePath);
+  }
+
+  if (!selectedProfilePath) {
+    return resolveBundledOrDefaultProfile(packageRoot, schema);
+  }
+
+  const selectedExists = await pathExists(selectedProfilePath);
+
+  if (!selectedExists) {
+    if (rawOptions.yes) {
+      return resolveBundledOrDefaultProfile(packageRoot, schema);
     }
 
-    await maybeInitializeProfileInteractively(packageRoot, requestedPath);
+    await maybeInitializeProfileInteractively(packageRoot, selectedProfilePath);
   }
 
-  return readAndValidateProfile(requestedPath, schema);
+  return {
+    profile: await readAndValidateProfile(selectedProfilePath, schema),
+    profilePathForMetadata: getRelativeProfilePath(selectedProfilePath, targetPath)
+  };
+}
+
+async function collectAiFiles(packageRoot) {
+  const aiFiles = ["AGENTS.md"];
+  const adaptersTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "adapters");
+  const examplesTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "examples");
+  const adapterEntries = await readdir(adaptersTemplateDir, { withFileTypes: true });
+
+  for (const entry of adapterEntries) {
+    if (!entry.isFile() || !entry.name.endsWith(".template.md")) {
+      continue;
+    }
+
+    aiFiles.push(path.join("ai", entry.name.replace(/\.template\.md$/, ".md")));
+  }
+
+  const exampleTemplateFiles = await collectTemplateFiles(examplesTemplateDir);
+
+  for (const exampleFile of exampleTemplateFiles) {
+    aiFiles.push(path.join("ai", "examples", exampleFile.targetRelativePath));
+  }
+
+  return aiFiles.sort((left, right) => left.localeCompare(right));
 }
 
 async function promptForMissing(options) {
@@ -880,11 +1264,12 @@ async function runInit(rawOptions) {
     throw new Error(`Invalid template: ${template}`);
   }
 
+  const targetPath = path.resolve(process.cwd());
   const packageRoot = resolvePackageRoot();
+  const packageVersion = await readPackageVersion(packageRoot);
   const schema = await loadProfileSchema(packageRoot);
-  const profile = await resolveProfileForInit(packageRoot, options, schema);
-
-  const targetPath = path.resolve(process.cwd());
+  const profileResolution = await resolveProfileForInit(packageRoot, targetPath, options, schema);
+  const profile = profileResolution.profile;
   const inferredProjectName = path.basename(targetPath);
   const projectName = inferredProjectName && inferredProjectName !== path.sep ? inferredProjectName : "my-project";
   const packageName = sanitizePackageName(projectName);
@@ -910,11 +1295,93 @@ async function runInit(rawOptions) {
     await runCommand("npm", ["install"], targetPath);
   }
 
+  const { packageJsonPath, packageJson } = await readProjectPackageJson(targetPath);
+  const packageWithMetadata = updateCodeStandardsMetadata(packageJson, {
+    template,
+    profilePath: profileResolution.profilePathForMetadata,
+    withAiAdapters: options.withAiAdapters,
+    lastRefreshWith: packageVersion
+  });
+  await writeProjectPackageJson(packageJsonPath, packageWithMetadata);
+
   console.log(`Project created at ${targetPath}`);
   console.log("Next steps:");
   console.log("  npm run check");
 }
 
+async function runRefresh(rawOptions) {
+  if (rawOptions.help) {
+    printUsage();
+    return;
+  }
+
+  const targetPath = path.resolve(process.cwd());
+  const packageRoot = resolvePackageRoot();
+  const packageVersion = await readPackageVersion(packageRoot);
+  const schema = await loadProfileSchema(packageRoot);
+  const { packageJsonPath, packageJson: projectPackageJson } = await readProjectPackageJson(targetPath);
+  const projectMetadata = asPlainObject(projectPackageJson[CODE_STANDARDS_METADATA_KEY]);
+  const template = await resolveTemplateForRefresh(rawOptions, projectPackageJson, targetPath);
+  const { templateDir } = await validateInitResources(packageRoot, template);
+  const profileResolution = await resolveProfileForRefresh(packageRoot, targetPath, rawOptions, schema, projectMetadata);
+  const inferredProjectName = path.basename(targetPath);
+  const projectName = inferredProjectName && inferredProjectName !== path.sep ? inferredProjectName : "my-project";
+  const currentPackageName =
+    typeof projectPackageJson.name === "string" && projectPackageJson.name.length > 0 ? projectPackageJson.name : sanitizePackageName(projectName);
+  const tokens = {
+    projectName,
+    packageName: currentPackageName,
+    year: String(new Date().getFullYear()),
+    profileSummary: JSON.stringify(profileResolution.profile)
+  };
+
+  const managedResults = await applyManagedFiles({
+    templateDir,
+    targetDir: targetPath,
+    tokens,
+    templateName: template,
+    projectPackageJson,
+    dryRun: rawOptions.dryRun
+  });
+  const aiFiles = rawOptions.withAiAdapters ? await collectAiFiles(packageRoot) : [];
+
+  if (rawOptions.dryRun) {
+    const uniqueFiles = [...new Set([...managedResults.updatedFiles, ...aiFiles])].sort((left, right) => left.localeCompare(right));
+    console.log(`Dry run: refresh would update ${uniqueFiles.length} file(s).`);
+
+    for (const filePath of uniqueFiles) {
+      console.log(`  - ${filePath}`);
+    }
+
+    if (rawOptions.install) {
+      console.log("Dry run: npm install would be executed.");
+    }
+
+    return;
+  }
+
+  if (rawOptions.withAiAdapters) {
+    await generateAiInstructions(packageRoot, targetPath, tokens, profileResolution.profile);
+  }
+
+  if (rawOptions.install) {
+    console.log("Installing dependencies...");
+    await runCommand("npm", ["install"], targetPath);
+  }
+
+  const packageWithMetadata = updateCodeStandardsMetadata(managedResults.mergedPackageJson, {
+    template,
+    profilePath: profileResolution.profilePathForMetadata,
+    withAiAdapters: rawOptions.withAiAdapters,
+    lastRefreshWith: packageVersion
+  });
+  await writeProjectPackageJson(packageJsonPath, packageWithMetadata);
+
+  console.log(`Project refreshed at ${targetPath}`);
+  console.log("Next steps:");
+  console.log("  npm run check");
+}
+
 async function main() {
   const argv = process.argv.slice(2);
 
@@ -931,6 +1398,11 @@ async function main() {
       return;
     }
 
+    if (command === "refresh" || command === "update") {
+      await runRefresh(parseRefreshArgs(rest));
+      return;
+    }
+
     if (command === "profile") {
       await runProfile(parseProfileArgs(rest));
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sha3/code-standards",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "AI-first code standards, tooling exports, and project initializer",
   "type": "module",
   "bin": {

package/resources/ai/templates/examples/demo/src/billing/billing-service.ts

@@ -8,7 +8,7 @@
  * @section imports:internals
  */
 
-import { BILLING_CURRENCY_SYMBOL, STATUS_SERVICE_URL } from "../config.js";
+import CONFIG from "../config.js";
 import type { InvoiceService } from "../invoices/invoice-service.js";
 import type { InvoiceSummary } from "../invoices/invoice-types.js";
 
@@ -83,7 +83,7 @@ export class BillingService {
    */
 
   private formatCurrency(amount: number): string {
-    const formattedAmount = `${BILLING_CURRENCY_SYMBOL}${amount.toFixed(2)}`;
+    const formattedAmount = `${CONFIG.BILLING_CURRENCY_SYMBOL}${amount.toFixed(2)}`;
     return formattedAmount;
   }
 
@@ -104,7 +104,7 @@ export class BillingService {
       invoiceCount: summary.count,
       totalAmount: summary.totalAmount,
       formattedTotal: this.formatCurrency(summary.totalAmount),
-      statusServiceUrl: STATUS_SERVICE_URL
+      statusServiceUrl: CONFIG.STATUS_SERVICE_URL
     };
     return snapshot;
   }

package/resources/ai/templates/examples/demo/src/config.ts

@@ -1,3 +1,7 @@
-export const MINIMUM_INVOICE_AMOUNT = 0;
-export const BILLING_CURRENCY_SYMBOL = "$";
-export const STATUS_SERVICE_URL = "https://status.example.com/health";
+const CONFIG = {
+  MINIMUM_INVOICE_AMOUNT: 0,
+  BILLING_CURRENCY_SYMBOL: "$",
+  STATUS_SERVICE_URL: "https://status.example.com/health"
+} as const;
+
+export default CONFIG;

package/resources/ai/templates/examples/demo/src/invoices/invoice-service.ts

@@ -8,7 +8,7 @@ import { randomUUID } from "node:crypto";
  * @section imports:internals
  */
 
-import { MINIMUM_INVOICE_AMOUNT } from "../config.js";
+import CONFIG from "../config.js";
 import { InvalidInvoiceCommandError } from "./invoice-errors.js";
 import type { CreateInvoiceCommand, Invoice, InvoiceSummary } from "./invoice-types.js";
 
@@ -81,7 +81,7 @@ export class InvoiceService {
       throw InvalidInvoiceCommandError.forReason("customerId is required");
     }
 
-    if (command.amount <= MINIMUM_INVOICE_AMOUNT) {
+    if (command.amount <= CONFIG.MINIMUM_INVOICE_AMOUNT) {
       throw InvalidInvoiceCommandError.forReason("amount must be greater than zero");
     }
   }

package/resources/ai/templates/rules/architecture.md

@@ -4,6 +4,7 @@
 - Each feature MUST keep its own domain model, application services, and infrastructure adapters grouped by feature.
 - Cross-feature imports MUST happen through explicit public entry points.
 - Hardcoded, non-parameterized configuration MUST be centralized in `src/config.ts` (for example, external service URLs).
+- `src/config.ts` MUST export a single default object and it MUST always be imported as `import CONFIG from ".../config.js"`.
 
 Good example:
 

package/resources/ai/templates/rules/functions.md

@@ -7,6 +7,7 @@
 - New implementation and test files MUST be `.ts`.
 - JavaScript source files (`.js`, `.mjs`, `.cjs`) are not allowed in `src/` or `test/`.
 - If a declaration/expression fits in one line within 160 chars, it MUST stay on one line.
+- If a function/method needs many inputs, define a named `<FunctionName>Options` type and pass one `options` parameter.
 
 Good example:
 

package/standards/architecture.md

@@ -23,3 +23,4 @@ Both templates SHOULD keep this baseline structure:
 - Keep feature modules cohesive.
 - Avoid cyclic dependencies.
 - Keep hardcoded application configuration centralized in `src/config.ts`.
+- `src/config.ts` MUST export a default object (for example `CONFIG`) and consumers MUST import it as `import CONFIG from "./config.js"`.

package/standards/style.md

@@ -18,7 +18,9 @@ All code MUST follow the canonical rules in `standards/manifest.json`.
 - Avoid `any` unless there is no viable alternative.
 - Prefer explicit return types for exported functions.
 - Use type-only imports when possible.
+- If a function/method needs many inputs, define a named `<FunctionName>Options` type and pass a single `options` parameter.
 - Always use braces in control flow (`if`, `else`, `for`, `while`, `do`).
+- `src/config.ts` MUST export a default object and it MUST always be imported as `import CONFIG from ".../config.js"`.
 
 ## Naming
 

package/templates/node-lib/README.md

@@ -0,0 +1,37 @@
+# 📚 {{packageName}}
+
+Libreria TypeScript lista para publicar y reutilizar.
+
+## TL;DR
+
+```bash
+npm install
+npm run check
+npm run build
+```
+
+## Uso
+
+```ts
+import { greet } from "./dist/index.js";
+
+console.log(greet("world"));
+```
+
+## Scripts
+
+- `npm run check`: lint + format check + typecheck + tests
+- `npm run fix`: aplica autofix de lint y prettier
+- `npm run build`: compila a `dist/`
+- `npm run test`: ejecuta tests con Node test runner
+
+## Estructura
+
+- `src/`: implementacion
+- `src/config.ts`: configuracion hardcodeada centralizada
+- `test/`: pruebas
+- `dist/`: salida de build
+
+## AI Workflow
+
+Si trabajas con asistentes, usa `AGENTS.md` y `ai/*.md` como reglas bloqueantes.

package/templates/node-lib/src/config.ts

@@ -1 +1,5 @@
-export const GREETING_PREFIX = "Hello";
+const CONFIG = {
+  GREETING_PREFIX: "Hello"
+} as const;
+
+export default CONFIG;

package/templates/node-lib/src/index.ts

@@ -1,5 +1,5 @@
-import { GREETING_PREFIX } from "./config.js";
+import CONFIG from "./config.js";
 
 export function greet(name: string): string {
-  return `${GREETING_PREFIX}, ${name}`;
+  return `${CONFIG.GREETING_PREFIX}, ${name}`;
 }

package/templates/node-service/README.md

@@ -0,0 +1,36 @@
+# 🚀 {{packageName}}
+
+Servicio TypeScript listo para ejecutar en local y evolucionar por features.
+
+## TL;DR
+
+```bash
+npm install
+npm run check
+npm run start
+```
+
+## Ejecucion
+
+```bash
+npm run start
+```
+
+El servicio arranca por defecto en `http://localhost:3000`.
+
+## Scripts
+
+- `npm run start`: inicia el servicio con `tsx`
+- `npm run check`: lint + format check + typecheck + tests
+- `npm run fix`: aplica autofix de lint y prettier
+- `npm run test`: ejecuta tests con Node test runner
+
+## Estructura
+
+- `src/`: implementacion
+- `src/config.ts`: configuracion hardcodeada centralizada
+- `test/`: pruebas
+
+## AI Workflow
+
+Si trabajas con asistentes, usa `AGENTS.md` y `ai/*.md` como reglas bloqueantes.

package/templates/node-service/src/config.ts

@@ -1,3 +1,7 @@
-export const RESPONSE_CONTENT_TYPE = "application/json";
-export const DEFAULT_PORT = 3000;
-export const EXTERNAL_STATUS_URL = "https://status.example.com/health";
+const CONFIG = {
+  RESPONSE_CONTENT_TYPE: "application/json",
+  DEFAULT_PORT: 3000,
+  EXTERNAL_STATUS_URL: "https://status.example.com/health"
+} as const;
+
+export default CONFIG;

package/templates/node-service/src/index.ts

@@ -1,16 +1,16 @@
 import { createServer } from "node:http";
-import { DEFAULT_PORT, EXTERNAL_STATUS_URL, RESPONSE_CONTENT_TYPE } from "./config.js";
+import CONFIG from "./config.js";
 
 export function buildServer() {
   return createServer((_, response) => {
     response.statusCode = 200;
-    response.setHeader("content-type", RESPONSE_CONTENT_TYPE);
-    response.end(JSON.stringify({ ok: true, statusSource: EXTERNAL_STATUS_URL }));
+    response.setHeader("content-type", CONFIG.RESPONSE_CONTENT_TYPE);
+    response.end(JSON.stringify({ ok: true, statusSource: CONFIG.EXTERNAL_STATUS_URL }));
   });
 }
 
 if (process.env.NODE_ENV !== "test") {
-  const port = Number(process.env.PORT ?? String(DEFAULT_PORT));
+  const port = Number(process.env.PORT ?? String(CONFIG.DEFAULT_PORT));
   const server = buildServer();
   server.listen(port, () => {
     console.log(`service listening on http://localhost:${port}`);