@sha3/code-standards 0.1.5 → 0.1.7

package/README.md

@@ -1,6 +1,6 @@
 <div align="center">
 
-# @sha3/code-standards
+# 📏 @sha3/code-standards
 
 **Scaffold TypeScript projects + enforce how AI writes code.**
 
@@ -117,10 +117,13 @@ 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 and complete integration docs (API + config + integration contract for other LLMs)
 - `.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.
 
 Generated project code is TypeScript-only: implementation and tests live in `.ts` files.

package/bin/code-standards.mjs

@@ -537,8 +537,10 @@ function getRelativeProfilePath(profilePath, targetPath) {
   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 resolvedProfilePath;
+    return null;
   }
 
   return relativePath;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sha3/code-standards",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "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/readme.md

@@ -7,6 +7,11 @@ Mandatory requirements:
 - README MUST clearly explain: what the project does, why it exists, and how to use it in under 60 seconds.
 - README MUST include practical copy/paste examples that are runnable.
 - README MUST include a fast path (`TL;DR` or `Quick Start`) and an in-depth reference section.
+- For libraries, README MUST be complete integration documentation for external teams and LLM agents.
+- README MUST include a public API reference section with exported members and behavior expectations.
+- README MUST include a dedicated integration section that shows how to install/import/use from another project.
+- README MUST include a configuration reference section (`src/config.ts`) with meaning of each constant.
+- README MUST include compatibility constraints (runtime, ESM/CJS expectations, TypeScript assumptions).
 - README MUST include a section for AI usage (how to instruct assistants to follow local standards).
 - README MUST avoid vague marketing language and focus on actionable guidance.
 - README MUST be visually structured with clean headings, concise lists, and code blocks.
@@ -16,6 +21,7 @@ Good example characteristics:
 
 - Starts with immediate value and one-command quick start.
 - Shows exact commands and expected flow.
+- Includes public API and integration contract without forcing reader to inspect source files.
 - Includes troubleshooting or FAQ for common confusion points.
 
 Bad example characteristics:

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/readme.md

@@ -3,6 +3,7 @@
 ## Goal
 
 Every repository README MUST be clear, actionable, and visually structured.
+For libraries, README MUST be complete integration documentation because other LLMs will use it as source-of-truth.
 
 ## Mandatory Sections
 
@@ -10,6 +11,11 @@ Every repository README MUST be clear, actionable, and visually structured.
 - TL;DR or Quick Start with copy/paste commands.
 - What it does and why it exists.
 - Setup and usage examples.
+- Installation requirements and exact install command.
+- Public API reference (exports, expected inputs/outputs, and behavior notes).
+- Integration guide (how to consume the library from another project).
+- Configuration reference (`src/config.ts` constants and impact).
+- Compatibility and constraints (runtime, module format, TypeScript expectations).
 - AI workflow section when the repository uses AI coding contracts.
 - Troubleshooting or FAQ.
 
@@ -23,3 +29,4 @@ Every repository README MUST be clear, actionable, and visually structured.
 ## Quality Bar
 
 A top-tier README lets a new engineer understand and run the project in under 5 minutes without asking additional questions.
+For libraries, a top-tier README also lets another LLM integrate the library in a different codebase without opening source files.

package/standards/style.md

@@ -20,6 +20,7 @@ All code MUST follow the canonical rules in `standards/manifest.json`.
 - 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,83 @@
+# 📚 {{packageName}}
+
+Reusable TypeScript library with a clear integration contract for external projects and LLM agents.
+
+## TL;DR
+
+```bash
+npm install
+npm run check
+npm run build
+```
+
+## Installation
+
+```bash
+npm install <library-name>
+```
+
+## Compatibility
+
+- Node.js 20+
+- ESM (`"type": "module"`)
+- Strict TypeScript
+
+## Public API
+
+### `greet(name: string): string`
+
+Returns a greeting using the configured prefix.
+
+```ts
+import { greet } from "<library-name>";
+
+const greeting = greet("world");
+console.log(greeting);
+```
+
+## Integration Guide (External Projects)
+
+1. Install the library with `npm install <library-name>`.
+2. Import only from the public entrypoint (`<library-name>`).
+3. Do not import internal paths (`src/*`, private `dist/*` files, or private modules).
+4. If you integrate with an LLM, treat this section as the integration contract.
+
+## Configuration (`src/config.ts`)
+
+Hardcoded configuration is centralized in `src/config.ts`.
+
+- `CONFIG.GREETING_PREFIX`: prefix used by `greet`.
+
+## Contract for LLM Integrators
+
+- This README is the source of truth for external integration.
+- The stable API is the one documented in `Public API`.
+- If API shape or observable behavior changes, update this README in the same change.
+
+## Scripts
+
+- `npm run check`: lint + format check + typecheck + tests
+- `npm run fix`: lint/prettier autofix
+- `npm run build`: compile to `dist/`
+- `npm run test`: tests con Node test runner
+
+## Structure
+
+- `src/`: implementation
+- `src/config.ts`: centralized configuration
+- `test/`: tests
+- `dist/`: build output
+
+## Troubleshooting
+
+### Import errors (ESM)
+
+Ensure the consumer project uses Node.js-compatible ESM.
+
+### Type errors
+
+Run `npm run typecheck` in the consumer project and verify TypeScript version compatibility.
+
+## AI Workflow
+
+If you work with assistants, treat `AGENTS.md` and `ai/*.md` as blocking rules.

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,70 @@
+# 🚀 {{packageName}}
+
+TypeScript service template ready for local execution and feature-based evolution.
+
+## TL;DR
+
+```bash
+npm install
+npm run check
+npm run start
+```
+
+## Run
+
+```bash
+npm run start
+```
+
+The service starts on `http://localhost:3000` by default.
+
+## Compatibility
+
+- Node.js 20+
+- ESM (`"type": "module"`)
+- Strict TypeScript
+
+## API HTTP
+
+### `GET /`
+
+- Response: `200 OK`
+- `content-type`: `application/json`
+- body: `{ "ok": true, "statusSource": "<url>" }`
+
+## Integration Guide (External Projects)
+
+1. Start the service with `npm run start`.
+2. Consume the root endpoint for health/status.
+3. Integrate through the HTTP contract, not through internal files.
+
+## Configuration (`src/config.ts`)
+
+Hardcoded configuration is centralized:
+
+- `CONFIG.RESPONSE_CONTENT_TYPE`
+- `CONFIG.DEFAULT_PORT`
+- `CONFIG.EXTERNAL_STATUS_URL`
+
+## Contract for LLM Integrators
+
+- This README defines the expected HTTP contract.
+- Payload/status/header changes require a README update in the same change.
+- For integration, use documented endpoints and do not assume internal details.
+
+## Scripts
+
+- `npm run start`: start the service with `tsx`
+- `npm run check`: lint + format check + typecheck + tests
+- `npm run fix`: apply lint/prettier autofix
+- `npm run test`: run tests with Node test runner
+
+## Structure
+
+- `src/`: implementation
+- `src/config.ts`: centralized hardcoded configuration
+- `test/`: tests
+
+## AI Workflow
+
+If you work with assistants, treat `AGENTS.md` and `ai/*.md` as blocking rules.

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}`);