create-chanom-app 0.1.0 → 0.3.0

package/README.md

@@ -31,7 +31,8 @@ Run with no flags, the CLI walks you through:
 1. **Project name** - the target directory (kebab-cased). Defaults to `my-chanom-app`.
 2. **Initialize a git repository?** - `git init` plus an initial commit.
 3. **Add commit hooks?** - husky + lint-staged + commitlint (only asked when git is enabled).
-4. **Install dependencies now?** - runs `<pm> install` after scaffolding.
+4. **Add agent coding standards?** - the `coding-standards` skill in `.agents/skills`, linked into `.claude/skills`.
+5. **Install dependencies now?** - runs `<pm> install` after scaffolding.
 
 Every prompt has a matching flag so you can pre-answer any of them (or all, with `--yes`).
 
@@ -43,6 +44,8 @@ Every prompt has a matching flag so you can pre-answer any of them (or all, with
 | `--git` / `--no-git`          | Initialize a git repository (default: yes)                |
 | `--commit-hooks`              | Add husky + lint-staged + commitlint (requires git)       |
 | `--no-commit-hooks`           | Skip the commit-hooks topping                             |
+| `--agent-skills`              | Add the coding-standards skill (default: yes)             |
+| `--no-agent-skills`           | Skip the agent-skills topping                             |
 | `--install` / `--no-install`  | Install dependencies after scaffolding (default: install) |
 | `--pm <pnpm\|npm\|yarn\|bun>` | Package manager to record (default: detected)             |
 | `-y`, `--yes`                 | Accept all defaults, no prompts (CI-friendly)             |
@@ -71,10 +74,13 @@ A minimal Vite + React + TS app wired to the chanom shared configs:
 - `oxlint.config.ts` / `oxfmt.config.ts` - re-exporting the [`@chanom/dev-config`](../dev-config) presets
 - `vitest.config.ts` and a sample `src/app.test.tsx`
 - `src/` - `main.tsx`, `app.tsx`, `index.css`, and type declarations
+- `.vscode/settings.json` and `.vscode/extensions.json` - editor settings that run oxfmt formatting and oxlint fixes on save through the [oxc extension](https://marketplace.visualstudio.com/items?itemName=oxc.oxc-vscode), which is recommended so teammates are prompted to install it
 - `index.html`, `.gitignore`, and a starter `README.md`
 
 With the **commit-hooks** topping, it also adds husky, lint-staged, and commitlint as dev dependencies plus their config files (`.husky/pre-commit`, `.husky/commit-msg`, `.lintstagedrc.json`, `.commitlintrc.json`). The hooks materialize on the first install via the generated `prepare: "husky"` script.
 
+With the **agent-skills** topping, it adds the `coding-standards` agent skill - a router `SKILL.md` plus TypeScript, React, and Vitest references written for exactly the stack scaffolded here. The real files land in `.agents/skills/coding-standards/` so any agent tool can read them, and `.claude/skills/coding-standards` is a relative symlink pointing at that directory rather than a second copy. It contributes no packages and no scripts, so skipping it leaves both directories out entirely.
+
 ## Development
 
 ```sh

package/dist/index.js

@@ -39,6 +39,43 @@ function resolvePm(hints) {
 	return parsePmField(hints.packageManagerField) ?? parsePmUserAgent(hints.userAgent) ?? hints.fallback ?? "pnpm";
 }
 //#endregion
+//#region ../internal/src/domain/vscode.ts
+/** Keys VS Code reads as a per-language override, e.g. `[typescript]`. */
+const LANGUAGES = [
+	"markdown",
+	"json",
+	"typescriptreact",
+	"typescript",
+	"javascript"
+];
+const OXC_FORMATTER = "oxc.oxc-vscode";
+/** The extensions a chanom project recommends; unioned into an existing list. */
+const RECOMMENDED_EXTENSIONS = [OXC_FORMATTER];
+/**
+* The VS Code settings chanom contributes. Every value is portable across
+* projects - repo-specific entries (`cSpell.words`, `git.*`) are deliberately
+* excluded so this can be dropped into any project without carrying chanom's
+* own choices.
+*
+* `editor.formatOnSave` is false on purpose: formatting runs through the oxc
+* code action instead, so formatting and lint fixes apply in one pass rather
+* than racing each other.
+*/
+function chanomSettings(oxfmtConfigPath) {
+	return {
+		"editor.defaultFormatter": OXC_FORMATTER,
+		"editor.formatOnSave": false,
+		"editor.codeActionsOnSave": {
+			"source.format.oxc": "always",
+			"source.fixAll.oxc": "always",
+			"source.removeUnusedImports": "always"
+		},
+		"oxc.fmt.configPath": oxfmtConfigPath,
+		"oxc.typeAware": true,
+		...Object.fromEntries(LANGUAGES.map((language) => [`[${language}]`, { "editor.defaultFormatter": OXC_FORMATTER }]))
+	};
+}
+//#endregion
 //#region ../internal/src/services/command-runner.ts
 const collectText = (stream) => stream.pipe(Stream.decodeText(), Stream.mkString);
 /**
@@ -169,6 +206,58 @@ var Prompter = class extends Effect.Service()("internal/Prompter", { succeed: {
 	})
 } }) {};
 //#endregion
+//#region ../internal/src/skills/index.ts
+/**
+* The coding-standards skill, targeting the stack `create-chanom-app` scaffolds
+* (Vite + React + TypeScript, oxlint, oxfmt, vitest). Its markdown is authored
+* as real `.md` files under `skills/coding-standards/` and inlined here at
+* build time through the `__CODING_STANDARDS_FILES__` define, so `chanom brew`
+* and `create-chanom-app` install byte-identical content from one source.
+*/
+const codingStandardsSkill = {
+	name: "coding-standards",
+	files: [
+		{
+			"path": "references/react.md",
+			"contents": "# React\n\nReact 19 with the Vite plugin. Entry is `src/main.tsx`, which mounts `App` from\n`src/app.tsx` in `StrictMode`.\n\n## Structure\n\n`src/` grows by role as the app does: `components/`, `hooks/`, `utils/`,\n`pages/`, `providers/`. Feature-scoped code lives under `features/<name>/` and\nmirrors that same layout. Put code in the feature folder unless two features\nshare it.\n\n## Components\n\n- **Container / presentational**: containers fetch data and hold logic;\n  presentational components take props and return JSX with no side effects.\n- Props are wrapped in `Readonly<>`:\n  `export function UserCard({ name }: Readonly<UserCardProps>)`.\n- Conditional rendering uses a ternary (`isOpen ? <Panel /> : null`), never\n  `&&` — a falsy number renders as `0`.\n- Every component exports inline. `default` export is reserved for route-level\n  page components.\n- Shared state lives in a context provider under `providers/`. Reach for\n  context only once prop-passing spans three levels.\n\n## Hooks\n\nCustom hooks are named `use-<thing>.ts` and return an object, not a positional\ntuple, once they return more than two values. Every effect declares its full\ndependency array; an effect with no cleanup and no async work is usually a\nrender-time computation instead.\n"
+		},
+		{
+			"path": "references/typescript.md",
+			"contents": "# TypeScript\n\n## Types\n\n- Never use `any`. Reach for generics and utility types; when you must escape\n  the type system use `unknown` and narrow explicitly.\n- Type-only imports use `import type { ... }`. A mixed import splits its type\n  part into a separate `import type` line.\n- Derive types from their source rather than restating them — `z.infer` for a\n  schema, `ReturnType`/`Parameters` for a function, `typeof` for a const object.\n  A hand-written duplicate drifts.\n- Props and params objects are declared as `interface`, named after their owner:\n  `interface UserCardProps`, `interface UseCurrentUserParams`.\n\n## Modules\n\n- Functions, not classes. Hooks, utils, factories, and components are plain\n  exported functions.\n- Export inline (`export function formatDate(...)`) rather than a trailing\n  `export { ... }` block.\n- Import order is enforced by oxlint — run `pnpm lint --fix` rather than\n  hand-sorting.\n\n## Errors\n\nThrow `Error` (or a subclass) with a message naming what failed and the value\nthat caused it. An unused catch binding is omitted: `catch {`, not\n`catch (_e) {`.\n"
+		},
+		{
+			"path": "references/vitest.md",
+			"contents": "# Vitest\n\nTests run on jsdom with globals enabled — `describe`, `it`, `expect`, and `vi`\nneed no import. `src/test-setup.ts` loads `@testing-library/jest-dom/vitest`, so\nits matchers are available everywhere. Run with `pnpm test`, or `pnpm test:watch`\nwhile iterating.\n\n## Layout\n\nTests are colocated and named `*.test.ts` / `*.test.tsx`, sitting beside the\nfile they cover: `src/app.tsx` → `src/app.test.tsx`.\n\n## Component tests\n\nTesting Library with `user-event`, querying by role and accessible name:\n\n```tsx\ndescribe('UserCard', () => {\n  it('should render the user name correctly', () => {\n    render(<UserCard name=\"Ada\" />);\n    expect(screen.getByRole('heading', { name: 'Ada' })).toBeInTheDocument();\n  });\n\n  it('should call onSelect when clicked', async () => {\n    const user = userEvent.setup();\n    const onSelect = vi.fn();\n    render(<UserCard name=\"Ada\" onSelect={onSelect} />);\n    await user.click(screen.getByRole('button', { name: 'Select' }));\n    expect(onSelect).toHaveBeenCalledTimes(1);\n  });\n});\n```\n\n- Interactions go through `userEvent.setup()` and `await user.click(...)`, not\n  `fireEvent`.\n- Handlers are `vi.fn()` asserted by call count, including the negative case —\n  a disabled control asserts `toHaveBeenCalledTimes(0)`.\n- Query by `getByRole` / `getByText`. Reach for `getByTestId` only when no\n  accessible query exists, such as a decorative spinner.\n- Assert on what the user observes, not on state or implementation details.\n\n## Naming\n\nTest names read `should <behaviour> correctly` or `should <effect> when\n<action>`. Group a unit's tests in one `describe` named for the unit.\n"
+		},
+		{
+			"path": "SKILL.md",
+			"contents": "---\nname: coding-standards\ndescription: Coding standards for this Vite + React + TypeScript app. Use when writing or changing components, hooks, utils, or tests, and before committing.\n---\n\n# Coding standards\n\nVite + React 19 + TypeScript, scaffolded with `create-chanom-app`. oxlint lints,\noxfmt formats, vitest tests. Read the reference for what you touch **before**\nwriting, so new code matches the code already here.\n\n## Which reference to load\n\n| You are writing…                             | Load                       |\n| -------------------------------------------- | -------------------------- |\n| Any `.ts` / `.tsx` file                      | `references/typescript.md` |\n| A component, hook, or anything rendering JSX | `references/react.md`      |\n| A `*.test.ts` / `*.test.tsx` file            | `references/vitest.md`     |\n\nThese layer: a new component with a test reads all three. Load every row that\napplies.\n\n## Universal rules\n\n- Filenames are kebab-case: `user-card.tsx`, `use-current-user.ts`, `format-date.ts`.\n- Before adding a file, open two neighbouring files of the same kind and match\n  their shape — import order, export style, test naming.\n- Source lives under `src/`. Colocate a test beside the code it covers:\n  `src/utils/format-date.ts` → `src/utils/format-date.test.ts`.\n\n## Verify\n\nAfter implementing, from the project root:\n\n```sh\npnpm lint\npnpm test\npnpm build\n```\n\nDone only when all three exit clean. On failure, fix and rerun until they do.\nRun `pnpm format` before committing. Comment- or doc-only changes may skip all\nfour.\n\n## Committing\n\nAsk before committing. Use conventional commits under 100 characters:\n`<type>(<scope>): <subject>`, e.g. `feat(auth): add sign-out button`. Scope is\nthe area you touched, not the repo name.\n"
+		}
+	]
+};
+/** Directory holding the real skill files, agent-agnostic. */
+const SKILLS_ROOT = ".agents/skills";
+/** Directory Claude Code reads skills from; its entries are links into {@link SKILLS_ROOT}. */
+const CLAUDE_SKILLS_ROOT = ".claude/skills";
+/** Files a skill writes, rooted at `.agents/skills/<name>/`. */
+function skillFiles(skill) {
+	return skill.files.map((file) => ({
+		path: `${SKILLS_ROOT}/${skill.name}/${file.path}`,
+		contents: file.contents
+	}));
+}
+/**
+* The `.claude/skills/<name>` link for a skill. Real files live under
+* `.agents/skills/` so any agent tool can read them; Claude Code only looks in
+* `.claude/skills/`, so it gets a link rather than a second copy.
+*/
+function skillLink(skill) {
+	return {
+		path: `${CLAUDE_SKILLS_ROOT}/${skill.name}`,
+		target: `../../${SKILLS_ROOT}/${skill.name}`
+	};
+}
+//#endregion
 //#region src/bundled-versions.ts
 const depVersions = {
 	"react": "19.2.8",
@@ -195,7 +284,7 @@ const depVersions = {
 	"@chanom/vite-config": "0.1.0"
 };
 /** This package's own version, for `--version`. */
-const pkgVersion = "0.1.0";
+const pkgVersion = "0.3.0";
 //#endregion
 //#region src/domain/args.ts
 const PACKAGE_MANAGERS = [
@@ -243,6 +332,12 @@ function parseArgs(argv) {
 			case "--no-commit-hooks":
 				args.commitHooks = false;
 				break;
+			case "--agent-skills":
+				args.agentSkills = true;
+				break;
+			case "--no-agent-skills":
+				args.agentSkills = false;
+				break;
 			case "--install":
 				args.install = true;
 				break;
@@ -305,16 +400,27 @@ function toKebabCase(name) {
 }
 //#endregion
 //#region src/domain/contribution.ts
+const emptyContribution = {
+	dependencies: [],
+	devDependencies: [],
+	scripts: {},
+	viteImports: [],
+	vitePlugins: [],
+	files: [],
+	links: []
+};
 const dedupe = (values) => [...new Set(values)];
 /**
 * Folds contributions in order into a single value. Package names, vite imports,
 * and plugins are concatenated then de-duplicated (first occurrence wins its
 * position); scripts merge with later contributions overriding earlier keys;
-* files de-duplicate by path (first writer wins).
+* files and links de-duplicate by path (first writer wins).
 */
 function mergeContributions(contributions) {
 	const filesByPath = /* @__PURE__ */ new Map();
 	for (const contribution of contributions) for (const file of contribution.files) if (!filesByPath.has(file.path)) filesByPath.set(file.path, file);
+	const linksByPath = /* @__PURE__ */ new Map();
+	for (const contribution of contributions) for (const link of contribution.links) if (!linksByPath.has(link.path)) linksByPath.set(link.path, link);
 	return {
 		dependencies: dedupe(contributions.flatMap((c) => c.dependencies)),
 		devDependencies: dedupe(contributions.flatMap((c) => c.devDependencies)),
@@ -324,7 +430,8 @@ function mergeContributions(contributions) {
 		}), {}),
 		viteImports: dedupe(contributions.flatMap((c) => c.viteImports)),
 		vitePlugins: dedupe(contributions.flatMap((c) => c.vitePlugins)),
-		files: [...filesByPath.values()]
+		files: [...filesByPath.values()],
+		links: [...linksByPath.values()]
 	};
 }
 //#endregion
@@ -515,6 +622,7 @@ const TEMPLATE_FILES = [
 ];
 //#endregion
 //#region src/toppings.ts
+const asJson = (value) => JSON.stringify(value, null, 2) + "\n";
 /**
 * The always-present baseline: a minimal Vite + React + TS app wired to the
 * chanom shared configs. Its static source files ship as verbatim templates;
@@ -553,7 +661,14 @@ const baseline = {
 	},
 	viteImports: ["import react from '@vitejs/plugin-react';"],
 	vitePlugins: ["react()"],
-	files: []
+	files: [{
+		path: ".vscode/settings.json",
+		contents: asJson(chanomSettings("oxfmt.config.ts"))
+	}, {
+		path: ".vscode/extensions.json",
+		contents: asJson({ recommendations: RECOMMENDED_EXTENSIONS })
+	}],
+	links: []
 };
 const LINT_STAGED_CONFIG = {
 	"**/*.{js,jsx,ts,tsx,mjs,cjs,mts,cts}": ["oxlint --fix --no-error-on-unmatched-pattern"],
@@ -600,12 +715,27 @@ function commitHooks(pm) {
 				path: ".commitlintrc.json",
 				contents: JSON.stringify(COMMITLINT_CONFIG, null, 2) + "\n"
 			}
-		]
+		],
+		links: []
 	};
 }
+/**
+* The `agent-skills` topping: the chanom coding-standards skill. Real files go
+* to `.agents/skills/` so any agent tool can read them, and `.claude/skills/`
+* gets a symlink rather than a second copy. Contributes files and links only -
+* no packages, no scripts - so projects that skip it get neither directory.
+*/
+const agentSkills = {
+	...emptyContribution,
+	files: skillFiles(codingStandardsSkill),
+	links: [skillLink(codingStandardsSkill)]
+};
 /** The baseline plus whichever toppings the resolved options select, in fold order. */
 function selectContributions(selection) {
-	return selection.commitHooks ? [baseline, commitHooks(selection.pm)] : [baseline];
+	const contributions = [baseline];
+	if (selection.commitHooks) contributions.push(commitHooks(selection.pm));
+	if (selection.agentSkills) contributions.push(agentSkills);
+	return contributions;
 }
 //#endregion
 //#region src/scaffold.ts
@@ -627,6 +757,25 @@ const copyTemplates = Effect.fn("scaffold.copyTemplates")(function* (plan) {
 		yield* writeFile(plan.targetDir, file.dest, contents);
 	}
 });
+/**
+* Creates one topping-contributed symlink, making its parent directory first.
+* Scaffolding into an existing directory (`create chanom-app .`) can meet a link
+* an earlier run - or `chanom add-skills` - already made, and `symlink` fails
+* with EEXIST on anything already there, so an occupied path is left alone and
+* reported instead of aborting the scaffold after the files are written.
+*/
+const writeLink = Effect.fn("scaffold.writeLink")(function* (targetDir, link) {
+	const fs = yield* FileSystem.FileSystem;
+	const path = yield* Path.Path;
+	const prompter = yield* Prompter;
+	const linkPath = path.join(targetDir, link.path);
+	if (yield* fs.exists(linkPath)) {
+		yield* prompter.warn(`\`${link.path}\` already exists - skipping link`);
+		return;
+	}
+	yield* fs.makeDirectory(path.dirname(linkPath), { recursive: true });
+	yield* fs.symlink(link.target, linkPath);
+});
 const writeGeneratedFiles = Effect.fn("scaffold.writeGeneratedFiles")(function* (plan, folded) {
 	const appName = toKebabCase(plan.appName);
 	yield* writeFile(plan.targetDir, "package.json", buildPackageJson({
@@ -640,6 +789,7 @@ const writeGeneratedFiles = Effect.fn("scaffold.writeGeneratedFiles")(function*
 	yield* writeFile(plan.targetDir, "tsconfig.json", buildTsconfig());
 	yield* writeFile(plan.targetDir, "index.html", renderIndexHtml(appName));
 	for (const file of folded.files) yield* writeFile(plan.targetDir, file.path, file.contents);
+	for (const link of folded.links) yield* writeLink(plan.targetDir, link);
 });
 const initGit = Effect.fn("scaffold.initGit")(function* (plan) {
 	const git = yield* Git;
@@ -665,7 +815,8 @@ const scaffold = Effect.fn("scaffold")(function* (plan) {
 	const fs = yield* FileSystem.FileSystem;
 	const folded = mergeContributions(selectContributions({
 		pm: plan.pm,
-		commitHooks: plan.commitHooks
+		commitHooks: plan.commitHooks,
+		agentSkills: plan.agentSkills
 	}));
 	yield* fs.makeDirectory(plan.targetDir, { recursive: true });
 	yield* copyTemplates(plan);
@@ -687,6 +838,8 @@ ${pc.bold("Options")}
   ${pc.cyan("--git / --no-git")}            Initialize a git repository (default: yes)
   ${pc.cyan("--commit-hooks")}              Add husky + lint-staged + commitlint (requires git)
   ${pc.cyan("--no-commit-hooks")}           Skip the commit-hooks topping
+  ${pc.cyan("--agent-skills")}              Add the coding-standards skill to .claude/skills
+  ${pc.cyan("--no-agent-skills")}           Skip the agent-skills topping
   ${pc.cyan("--install / --no-install")}    Install dependencies after scaffolding (default: install)
   ${pc.cyan("--pm <pnpm|npm|yarn|bun>")}    Package manager to record (default: detected)
   ${pc.cyan("-y, --yes")}                   Accept all defaults, no prompts (CI-friendly)
@@ -758,6 +911,10 @@ const program$1 = (argv, cwd, options) => Effect.gen(function* () {
 		message: "Add commit hooks (husky + lint-staged + commitlint)?",
 		initialValue: true
 	})) : false;
+	const agentSkills = yield* resolveConfirm(args.agentSkills, args.yes, prompter.confirm({
+		message: "Add agent coding standards (.agents/skills)?",
+		initialValue: true
+	}));
 	const install = yield* resolveConfirm(args.install, args.yes, prompter.confirm({
 		message: "Install dependencies now?",
 		initialValue: true
@@ -771,6 +928,7 @@ const program$1 = (argv, cwd, options) => Effect.gen(function* () {
 		`${pc.dim("package mgr")}   ${pm}`,
 		`${pc.dim("git")}           ${git ? "yes" : "no"}`,
 		`${pc.dim("commit hooks")}  ${git ? commitHooks ? "yes" : "no" : pc.dim("n/a")}`,
+		`${pc.dim("agent skills")}  ${agentSkills ? "yes" : "no"}`,
 		`${pc.dim("install")}       ${install ? "yes" : "no"}`
 	].join("\n"));
 	yield* scaffold({
@@ -780,6 +938,7 @@ const program$1 = (argv, cwd, options) => Effect.gen(function* () {
 		packageManagerField: packageManagerField(pm, options.userAgent),
 		git,
 		commitHooks,
+		agentSkills,
 		install,
 		templatesRoot: options.templatesRoot
 	});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-chanom-app",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Scaffold a Vite + React + TypeScript app, wired to the chanom shared configs.",
   "keywords": [
     "create",