@sha3/code-standards 0.1.0 → 0.1.2

package/README.md

@@ -18,7 +18,7 @@
 If you just want to start now:
 
 ```bash
-npx @sha3/code-standards init my-api --template node-service --yes
+npx @sha3/code-standards init --template node-service --yes
 ```
 
 Then in your AI chat, paste this:
@@ -64,7 +64,9 @@ Default generated contract includes structural class/file blocks such as:
 
 Section marker format is fixed to:
 
-- `/** @section <block-name> */`
+- `/**`
+- ` * @section <block-name>`
+- ` */`
 
 All blocks MUST exist even when empty (`// empty`).
 
@@ -85,14 +87,14 @@ No.
 Default flow (no profile setup):
 
 ```bash
-npx @sha3/code-standards init my-app --template node-service --yes
+npx @sha3/code-standards init --template node-service --yes
 ```
 
 Custom profile flow:
 
 ```bash
 npx @sha3/code-standards profile --profile ./profiles/team.profile.json
-npx @sha3/code-standards init my-app --template node-service --yes --profile ./profiles/team.profile.json
+npx @sha3/code-standards init --template node-service --yes --profile ./profiles/team.profile.json
 ```
 
 ---
@@ -103,10 +105,43 @@ After `init`, your new repo contains:
 
 - `AGENTS.md` (blocking rules for AI)
 - `ai/codex.md`, `ai/cursor.md`, `ai/copilot.md`, `ai/windsurf.md`
+- `ai/examples/rules/*.ts` (good/bad examples per rule)
+- `ai/examples/demo/src/*` (feature-folder demo with classes and section blocks)
+- `.gitignore` preconfigured for Node/TypeScript output
 - lint/format/typecheck/test-ready project template
 
 That means the next step is **not** configuring tools. The next step is telling your assistant to obey `AGENTS.md` before coding.
 
+## TypeScript Example Files
+
+`init` now stores code examples in `.ts` files instead of embedding them inside `AGENTS.md`.
+
+Demo structure generated by default:
+
+- `ai/examples/demo/src/invoices/invoice-service.ts`
+- `ai/examples/demo/src/invoices/invoice-errors.ts`
+- `ai/examples/demo/src/invoices/invoice-types.ts`
+- `ai/examples/demo/src/billing/billing-service.ts`
+
+Rule-specific examples:
+
+- `ai/examples/rules/class-first-good.ts`
+- `ai/examples/rules/class-first-bad.ts`
+- `ai/examples/rules/constructor-good.ts`
+- `ai/examples/rules/constructor-bad.ts`
+- `ai/examples/rules/functions-good.ts`
+- `ai/examples/rules/functions-bad.ts`
+- `ai/examples/rules/returns-good.ts`
+- `ai/examples/rules/returns-bad.ts`
+- `ai/examples/rules/async-good.ts`
+- `ai/examples/rules/async-bad.ts`
+- `ai/examples/rules/control-flow-good.ts`
+- `ai/examples/rules/control-flow-bad.ts`
+- `ai/examples/rules/errors-good.ts`
+- `ai/examples/rules/errors-bad.ts`
+- `ai/examples/rules/testing-good.ts`
+- `ai/examples/rules/testing-bad.ts`
+
 ---
 
 ## How To Use With AI (Copy/Paste)
@@ -197,14 +232,16 @@ npx @sha3/code-standards profile \
 
 ### 2) Scaffold project
 
+Run this inside the directory you want to initialize.
+
 ```bash
-npx @sha3/code-standards init my-api --template node-service --yes
+npx @sha3/code-standards init --template node-service --yes
 ```
 
 With explicit profile:
 
 ```bash
-npx @sha3/code-standards init my-lib \
+npx @sha3/code-standards init \
   --template node-lib \
   --yes \
   --no-install \
@@ -214,7 +251,7 @@ npx @sha3/code-standards init my-lib \
 Skip AI files when needed:
 
 ```bash
-npx @sha3/code-standards init my-lib --template node-lib --yes --no-ai-adapters
+npx @sha3/code-standards init --template node-lib --yes --no-ai-adapters
 ```
 
 ### 3) Work loop inside generated project
@@ -234,15 +271,16 @@ Then use the prompts above in your AI tool.
 code-standards <command> [options]
 
 Commands:
-  init [project-name]   Initialize a project from templates
+  init                  Initialize a project in the current directory
   profile               Create or update the AI style profile
 ```
 
 ### `init` options
 
+`init` always uses the current working directory as target.
+
 - `--template <node-lib|node-service>`
 - `--yes`
-- `--target <dir>`
 - `--no-install`
 - `--force`
 - `--with-ai-adapters`

package/bin/code-standards.mjs

@@ -166,13 +166,12 @@ function printUsage() {
   code-standards <command> [options]
 
 Commands:
-  init [project-name]   Initialize a project from templates
+  init                  Initialize a project in the current directory
   profile               Create or update the AI style profile
 
 Init options:
   --template <node-lib|node-service>
   --yes
-  --target <dir>
   --no-install
   --force
   --with-ai-adapters
@@ -192,11 +191,9 @@ function parseInitArgs(argv) {
   const options = {
     template: undefined,
     yes: false,
-    target: undefined,
     install: true,
     force: false,
     withAiAdapters: true,
-    projectName: undefined,
     profilePath: undefined,
     help: false
   };
@@ -205,12 +202,9 @@ function parseInitArgs(argv) {
     const token = argv[i];
 
     if (!token.startsWith("-")) {
-      if (!options.projectName) {
-        options.projectName = token;
-        continue;
-      }
-
-      throw new Error(`Unexpected positional argument: ${token}`);
+      throw new Error(
+        `Positional project names are not supported: ${token}. Run init from your target directory.`
+      );
     }
 
     if (token === "--template") {
@@ -230,15 +224,7 @@ function parseInitArgs(argv) {
     }
 
     if (token === "--target") {
-      const value = argv[i + 1];
-
-      if (!value || value.startsWith("-")) {
-        throw new Error("Missing value for --target");
-      }
-
-      options.target = value;
-      i += 1;
-      continue;
+      throw new Error("--target is not supported. Run init from your target directory.");
     }
 
     if (token === "--profile") {
@@ -354,6 +340,15 @@ function replaceTokens(content, tokens) {
   return output;
 }
 
+function mapTemplateFileName(fileName) {
+  // npm may rewrite .gitignore to .npmignore in published tarballs.
+  if (fileName === "gitignore" || fileName === ".npmignore") {
+    return ".gitignore";
+  }
+
+  return fileName;
+}
+
 function normalizeProfile(rawProfile) {
   const normalized = {};
 
@@ -413,9 +408,9 @@ async function copyTemplateDirectory(sourceDir, targetDir, tokens) {
 
   for (const entry of entries) {
     const sourcePath = path.join(sourceDir, entry.name);
-    const targetPath = path.join(targetDir, entry.name);
 
     if (entry.isDirectory()) {
+      const targetPath = path.join(targetDir, entry.name);
       await copyTemplateDirectory(sourcePath, targetPath, tokens);
       continue;
     }
@@ -426,6 +421,8 @@ async function copyTemplateDirectory(sourceDir, targetDir, tokens) {
 
     const raw = await readFile(sourcePath, "utf8");
     const rendered = replaceTokens(raw, tokens);
+    const targetName = mapTemplateFileName(entry.name);
+    const targetPath = path.join(targetDir, targetName);
     await writeFile(targetPath, rendered, "utf8");
   }
 }
@@ -790,9 +787,16 @@ async function renderAdapterFiles(packageRoot, targetDir, tokens) {
   }
 }
 
+async function renderExampleFiles(packageRoot, targetDir, tokens) {
+  const examplesTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "examples");
+  const examplesTarget = path.join(targetDir, "ai", "examples");
+  await copyTemplateDirectory(examplesTemplateDir, examplesTarget, tokens);
+}
+
 async function generateAiInstructions(packageRoot, targetDir, tokens, profile) {
   await renderProjectAgents(packageRoot, targetDir, tokens.projectName, profile);
   await renderAdapterFiles(packageRoot, targetDir, tokens);
+  await renderExampleFiles(packageRoot, targetDir, tokens);
 }
 
 async function maybeInitializeProfileInteractively(packageRoot, profilePath) {
@@ -881,17 +885,6 @@ async function promptForMissing(options) {
       resolved.template = normalized;
     }
 
-    if (!resolved.projectName) {
-      const nameAnswer = await rl.question("Project name [my-project]: ");
-      resolved.projectName = nameAnswer.trim() || "my-project";
-    }
-
-    if (!resolved.target) {
-      const targetDefault = resolved.projectName;
-      const targetAnswer = await rl.question(`Target directory [${targetDefault}]: `);
-      resolved.target = targetAnswer.trim() || targetDefault;
-    }
-
     if (options.install) {
       const installAnswer = await rl.question("Install dependencies now? (Y/n): ");
       const normalized = installAnswer.trim().toLowerCase();
@@ -914,10 +907,12 @@ async function validateInitResources(packageRoot, templateName) {
     "agents.project.template.md"
   );
   const adaptersTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "adapters");
+  const examplesTemplateDir = path.join(packageRoot, "resources", "ai", "templates", "examples");
 
   await access(templateDir, constants.R_OK);
   await access(agentsTemplatePath, constants.R_OK);
   await access(adaptersTemplateDir, constants.R_OK);
+  await access(examplesTemplateDir, constants.R_OK);
 
   return { templateDir };
 }
@@ -932,8 +927,6 @@ async function runInit(rawOptions) {
 
   if (options.yes) {
     options.template ??= "node-lib";
-    options.projectName ??= "my-project";
-    options.target ??= options.projectName;
   } else {
     options = await promptForMissing(options);
   }
@@ -948,9 +941,11 @@ async function runInit(rawOptions) {
   const schema = await loadProfileSchema(packageRoot);
   const profile = await resolveProfileForInit(packageRoot, options, schema);
 
-  const projectName = options.projectName ?? path.basename(options.target ?? "my-project");
+  const targetPath = path.resolve(process.cwd());
+  const inferredProjectName = path.basename(targetPath);
+  const projectName =
+    inferredProjectName && inferredProjectName !== path.sep ? inferredProjectName : "my-project";
   const packageName = sanitizePackageName(projectName);
-  const targetPath = path.resolve(process.cwd(), options.target ?? projectName);
 
   await ensureTargetReady(targetPath, options.force);
 
@@ -975,7 +970,6 @@ async function runInit(rawOptions) {
 
   console.log(`Project created at ${targetPath}`);
   console.log("Next steps:");
-  console.log(`  cd ${targetPath}`);
   console.log("  npm run check");
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sha3/code-standards",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI-first code standards, tooling exports, and project initializer",
   "type": "module",
   "bin": {
@@ -51,10 +51,12 @@
     "hooks:install": "git config core.hooksPath .githooks",
     "profile:validate": "node scripts/validate-profile.mjs"
   },
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
   "devDependencies": {
     "@eslint/js": "^9.20.0",
     "@types/node": "^22.13.10",
-    "ajv": "^8.17.1",
     "eslint": "^9.20.1",
     "globals": "^15.15.0",
     "prettier": "^3.5.3",

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

@@ -0,0 +1,102 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+import type { InvoiceService } from "../invoices/invoice-service.js";
+import type { InvoiceSummary } from "../invoices/invoice-types.js";
+
+/**
+ * @section consts
+ */
+
+const CURRENCY_SYMBOL = "$";
+
+/**
+ * @section types
+ */
+
+export type BillingSnapshot = {
+  customerId: string;
+  invoiceCount: number;
+  totalAmount: number;
+  formattedTotal: string;
+};
+
+export class BillingService {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly invoiceService: InvoiceService;
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(invoiceService: InvoiceService) {
+    this.invoiceService = invoiceService;
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(invoiceService: InvoiceService): BillingService {
+    const service = new BillingService(invoiceService);
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private formatCurrency(amount: number): string {
+    const formattedAmount = `${CURRENCY_SYMBOL}${amount.toFixed(2)}`;
+    return formattedAmount;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async snapshot(customerId: string): Promise<BillingSnapshot> {
+    const summary: InvoiceSummary = await this.invoiceService.summarizeForCustomer(customerId);
+    const snapshot: BillingSnapshot = {
+      customerId,
+      invoiceCount: summary.count,
+      totalAmount: summary.totalAmount,
+      formattedTotal: this.formatCurrency(summary.totalAmount)
+    };
+    return snapshot;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,89 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+// empty
+
+/**
+ * @section types
+ */
+
+// empty
+
+export class InvalidInvoiceCommandError extends Error {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly reason: string;
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(reason: string) {
+    super(`Invalid invoice command: ${reason}`);
+    this.name = "InvalidInvoiceCommandError";
+    this.reason = reason;
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static forReason(reason: string): InvalidInvoiceCommandError {
+    const error = new InvalidInvoiceCommandError(reason);
+    return error;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  // empty
+
+  /**
+   * @section public:methods
+   */
+
+  public getReason(): string {
+    const value = this.reason;
+    return value;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,123 @@
+/**
+ * @section imports:externals
+ */
+
+import { randomUUID } from "node:crypto";
+
+/**
+ * @section imports:internals
+ */
+
+import { InvalidInvoiceCommandError } from "./invoice-errors.js";
+import type { CreateInvoiceCommand, Invoice, InvoiceSummary } from "./invoice-types.js";
+
+/**
+ * @section consts
+ */
+
+const MINIMUM_INVOICE_AMOUNT = 0;
+
+/**
+ * @section types
+ */
+
+// empty
+
+export class InvoiceService {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly invoicesById: Map<string, Invoice>;
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  public constructor() {
+    this.invoicesById = new Map<string, Invoice>();
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceService {
+    const service = new InvoiceService();
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private validate(command: CreateInvoiceCommand): void {
+    if (!command.customerId.trim()) {
+      throw InvalidInvoiceCommandError.forReason("customerId is required");
+    }
+
+    if (command.amount <= MINIMUM_INVOICE_AMOUNT) {
+      throw InvalidInvoiceCommandError.forReason("amount must be greater than zero");
+    }
+  }
+
+  private toInvoice(command: CreateInvoiceCommand): Invoice {
+    const invoice: Invoice = {
+      id: randomUUID(),
+      customerId: command.customerId,
+      amount: command.amount,
+      issuedAt: new Date()
+    };
+    return invoice;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    this.validate(command);
+    const createdInvoice: Invoice = this.toInvoice(command);
+    this.invoicesById.set(createdInvoice.id, createdInvoice);
+    return createdInvoice;
+  }
+
+  public async summarizeForCustomer(customerId: string): Promise<InvoiceSummary> {
+    const allInvoices: Invoice[] = Array.from(this.invoicesById.values());
+    const invoices: Invoice[] = allInvoices.filter((invoice) => {
+      return invoice.customerId === customerId;
+    });
+    const totalAmount = invoices.reduce((sum, invoice) => {
+      return sum + invoice.amount;
+    }, 0);
+    const summary: InvoiceSummary = {
+      count: invoices.length,
+      totalAmount
+    };
+    return summary;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

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

@@ -0,0 +1,20 @@
+export type InvoiceId = string;
+
+export type CustomerId = string;
+
+export type Invoice = {
+  id: InvoiceId;
+  customerId: CustomerId;
+  amount: number;
+  issuedAt: Date;
+};
+
+export type CreateInvoiceCommand = {
+  customerId: CustomerId;
+  amount: number;
+};
+
+export type InvoiceSummary = {
+  count: number;
+  totalAmount: number;
+};