@clearlydev/nx-archweave 0.0.0-stage → 0.1.0

package/dist/generators/shared/toolkit-config-file.js

@@ -0,0 +1,110 @@
+import { DEFAULT_AI_HOSTS, detectWorkspacePackageManager, isAiHost } from '@nx-archweave/template-engine';
+export const TOOLKIT_CONFIG_PATH = 'toolkit.config.json';
+/** The indentation unit an existing JSON file uses, so an update preserves the
+ * author's formatting: the first indented line's leading run of tabs or spaces,
+ * else two spaces (e.g. minified JSON or no file). */
+export function detectIndent(raw) {
+    for (const line of raw.split('\n')) {
+        const match = /^(\t+| +)/.exec(line);
+        if (match)
+            return match[1];
+    }
+    return '  ';
+}
+/** Best-effort read of toolkit.config.json. Never throws: the generators that read
+ * defaults from it (locale, boundaries, teamRules) must not abort on a broken file
+ * they do not own, and the ones that merge into it refuse to rewrite an
+ * unrecognized shape — both decide from this one result. */
+export function readToolkitConfigFile(tree) {
+    const raw = tree.read(TOOLKIT_CONFIG_PATH, 'utf-8');
+    if (raw === null)
+        return { raw: null, parsed: null };
+    try {
+        const parsed = JSON.parse(raw);
+        return {
+            raw,
+            parsed: typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : null,
+        };
+    }
+    catch {
+        return { raw, parsed: null };
+    }
+}
+/** The parsed object only — for readers that just want defaults. */
+export function readToolkitConfig(tree) {
+    return readToolkitConfigFile(tree).parsed;
+}
+/** option > toolkit.config.json `locale` > 'en' — the fallback every content
+ * generator shares; anything that is not ko/en is ignored, never an abort. */
+export function resolveLocaleOption(option, config) {
+    if (option)
+        return option;
+    const locale = config?.['locale'];
+    return locale === 'ko' || locale === 'en' ? locale : 'en';
+}
+/** A recorded choice init wrote, when it is one of `allowed`; anything else is ignored. */
+export function recordedChoice(config, key, allowed) {
+    const value = config?.[key];
+    return typeof value === 'string' && allowed.includes(value) ? value : undefined;
+}
+export const RECORDED_FRONTENDS = ['react-vite', 'next', 'none'];
+export const RECORDED_BACKENDS = ['express', 'nest', 'none'];
+export const RECORDED_PRESETS = ['quick-start', 'solo', 'team'];
+export const RECORDED_PACKAGE_MANAGERS = ['pnpm', 'npm', 'yarn', 'bun'];
+/** option > toolkit.config.json `frontend` (init records it); a run without either cannot
+ * pick the layer set, so it stops with the flag to pass. A backend-only workspace
+ * (`frontend: none`) has no frontend to structure, which stops the FSD generators too. */
+export function resolveFrontendOption(option, config, generator) {
+    const frontend = option ?? recordedChoice(config, 'frontend', RECORDED_FRONTENDS);
+    if (frontend === undefined) {
+        throw new Error(`${generator}: pass --frontend=react-vite|next (toolkit.config.json records none — init writes it).`);
+    }
+    if (frontend === 'none') {
+        throw new Error(`${generator}: this is a backend-only workspace (toolkit.config.json frontend: none) — FSD structures a frontend app. Pass --frontend=react-vite|next if you added one.`);
+    }
+    return frontend;
+}
+/** init's frontend axis: like resolveFrontendOption, but `none` (backend-only) is a choice. */
+export function resolveInitFrontend(option, config) {
+    const frontend = option ?? recordedChoice(config, 'frontend', RECORDED_FRONTENDS);
+    if (frontend === undefined) {
+        throw new Error('init: pass --frontend=react-vite|next|none (toolkit.config.json records none — init writes it).');
+    }
+    return frontend;
+}
+/** The workspace's package manager: its lockfiles first (they are what installs run with,
+ * even after a switch), then the one init recorded; null when neither says. */
+export function workspacePackageManager(exists, read, config) {
+    return detectWorkspacePackageManager(exists, read) ?? recordedChoice(config, 'packageManager', RECORDED_PACKAGE_MANAGERS) ?? null;
+}
+export function treePackageManager(tree, config) {
+    return workspacePackageManager((p) => tree.exists(p), (p) => tree.read(p, 'utf-8'), config);
+}
+/** Option (non-empty, deduped) > toolkit.config.json `aiHosts`
+ * (its known ids) > Claude Code. Shared by add-agent-rules and init, so a standalone run of
+ * either keeps the hosts a workspace was set up for. */
+export function resolveAiHostsOption(option, config) {
+    if (option !== undefined && option.length > 0)
+        return [...new Set(option)];
+    const recorded = config?.['aiHosts'];
+    const fromConfig = Array.isArray(recorded) ? [...new Set(recorded.filter(isAiHost))] : [];
+    return fromConfig.length > 0 ? fromConfig : [...DEFAULT_AI_HOSTS];
+}
+/** Writes `aiHosts` into toolkit.config.json: merge-preserving (every other key survives),
+ * indent-preserving, idempotent; a file that is not a JSON object is never rewritten. */
+export function recordAiHosts(tree, hosts, write) {
+    const { raw, parsed } = readToolkitConfigFile(tree);
+    if (raw !== null && parsed === null)
+        return 'unrecognized';
+    const existing = parsed ?? {};
+    const recorded = existing['aiHosts'];
+    if (Array.isArray(recorded) && recorded.length === hosts.length && recorded.every((id, index) => id === hosts[index])) {
+        return 'unchanged';
+    }
+    if (write) {
+        const indent = raw === null ? '  ' : detectIndent(raw);
+        const body = JSON.stringify({ ...existing, aiHosts: [...hosts] }, null, indent);
+        tree.write(TOOLKIT_CONFIG_PATH, raw === null || raw.endsWith('\n') ? `${body}\n` : body);
+    }
+    return raw === null ? 'created' : 'updated';
+}

package/dist/generators/slice/core.js

@@ -0,0 +1,185 @@
+import { join } from 'node:path';
+import { isEssenceSegmentName, isUsableSliceApiName, resolveSlicePublicApiName, SEGMENT_NAME_PATTERN, } from '@nx-archweave/template-engine';
+import { readToolkitConfig, RECORDED_FRONTENDS, resolveLocaleOption } from "../shared/toolkit-config-file.js";
+import { resolveFrontendApp } from "../shared/frontend-app.js";
+import { generatorFilesDir, renderTemplateFiles } from "../shared/template-files.js";
+/**
+ * A slice on a sliced layer, from this generator's `files/`:
+ *   <src>/<layer>/<name>/index.ts             public API          (files/index)
+ *   <src>/<layer>/<name>/model/<name>.ts      the stub            (files/module)
+ *   <src>/<layer>/<name>/model/<name>.spec.ts
+ *   <src>/<layer>/<name>/<segment>/index.ts   per --segments      (files/segment)
+ * A shared segment holds no segments of its own, so its stub sits next to the index.
+ */
+export function composeSlice(input) {
+    const files = generatorFilesDir('slice', import.meta.url);
+    const directory = `${input.sourceRoot}/${input.layerDirName}/${input.name}`;
+    const shared = input.layer === 'shared';
+    const values = {
+        name: input.name,
+        publicApiName: input.publicApiName,
+        layer: input.layer,
+        locale: input.locale,
+        modulePath: shared ? `./${input.name}` : `./model/${input.name}`,
+    };
+    const module = renderTemplateFiles(join(files, 'module'), shared ? directory : `${directory}/model`, values)
+        // the stub before its test
+        .sort((a, b) => Number(a.filePath.endsWith('.spec.ts')) - Number(b.filePath.endsWith('.spec.ts')));
+    const segments = shared
+        ? []
+        : Array.from(new Set(input.segments))
+            .filter((segment) => segment !== 'model')
+            .flatMap((segment) => renderTemplateFiles(join(files, 'segment'), `${directory}/${segment}`, { ...values, segment }));
+    return {
+        directory,
+        publicApiName: input.publicApiName,
+        files: [...renderTemplateFiles(join(files, 'index'), directory, values), ...module, ...segments],
+    };
+}
+/** Lowercase letters/digits, single hyphens, no leading/trailing/doubled hyphen, must
+ * start with a letter (so `toCamelCase`/directory names stay valid identifiers). */
+const KEBAB_CASE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+/** Next.js reads `src/pages` as its Pages Router, so FSD's Next.js guide puts the pages
+ * layer in `_pages/` there (as add-fsd-lite's guide says). Every other layer is its id. */
+function layerDirNameFor(layer, frontend) {
+    return layer === 'pages' && frontend === 'next' ? '_pages' : layer;
+}
+function layerDirFor(layer, sourceRoot, frontend = 'react-vite') {
+    return `${sourceRoot}/${layerDirNameFor(layer, frontend)}`;
+}
+const NEXT_CONFIG_FILES = ['next.config.js', 'next.config.mjs', 'next.config.ts', 'next.config.cjs'];
+/** option > toolkit.config.json's frontend (init records it) > a next.config file in the app
+ * (Nx's Next.js app always has one) > react-vite. Best-effort: it only moves `pages` to
+ * `_pages`, so a wrong guess costs a rename, never a broken file. */
+function resolveFrontendForApp(option, config, appRoot, tree) {
+    if (option === 'react-vite' || option === 'next')
+        return option;
+    const recorded = config?.['frontend'];
+    if (typeof recorded === 'string' && RECORDED_FRONTENDS.includes(recorded) && recorded !== 'none') {
+        return recorded;
+    }
+    const prefix = appRoot === '' || appRoot === '.' ? '' : `${appRoot}/`;
+    return NEXT_CONFIG_FILES.some((file) => tree.exists(`${prefix}${file}`)) ? 'next' : 'react-vite';
+}
+/** A slice directory is:
+ * - 'created' when it doesn't exist yet;
+ * - 'unchanged' when it exists and contains exactly our generated files, byte-for-byte;
+ * - 'skipped' for anything else (same-name slice already there with different/extra
+ *   content — a name collision is a signal to pick a new name; merge is never proposed). */
+/** Every file under `dir`, as paths relative to it (the generated set spans model/). */
+function listFilesUnder(tree, dir, prefix = '') {
+    return tree.children(dir).flatMap((child) => {
+        const path = `${dir}/${child}`;
+        return tree.isFile(path) ? [`${prefix}${child}`] : listFilesUnder(tree, path, `${prefix}${child}/`);
+    });
+}
+function computeSliceAction(tree, plan) {
+    if (!tree.exists(plan.directory))
+        return 'created';
+    const expectedNames = plan.files.map((f) => f.filePath.slice(plan.directory.length + 1)).sort();
+    const actualNames = listFilesUnder(tree, plan.directory).sort();
+    if (actualNames.length !== expectedNames.length || !actualNames.every((n, i) => n === expectedNames[i])) {
+        return 'skipped';
+    }
+    const allMatch = plan.files.every((f) => tree.read(f.filePath, 'utf-8') === f.content);
+    return allMatch ? 'unchanged' : 'skipped';
+}
+function refusal(reason, dryRun, layer, name, app, extra = {}) {
+    const layerDir = layerDirFor(layer, app.sourceRoot);
+    return {
+        dryRun,
+        layer,
+        name,
+        project: app.project,
+        layerDir,
+        directory: `${layerDir}/${name}`,
+        publicApiName: null,
+        refused: true,
+        refusalReason: reason,
+        action: null,
+        files: [],
+        ...extra,
+    };
+}
+/**
+ * Pure core shared by the `page` / `widget` / `feature` / `entity` / `shared` generators.
+ * `layer` is fixed per top-level generator — only the option parsing, tree reads, and
+ * report shape are shared here.
+ *
+ * The layer directory (`<app sourceRoot>/<layer>`) appears with its first slice (canonical
+ * FSD) — nothing has to exist beforehand but the frontend app.
+ */
+export function runFsdSlice(tree, layer, options) {
+    const dryRun = options.dryRun ?? false;
+    // Placeholder location for refusals raised before an app is picked.
+    const unresolved = { project: null, sourceRoot: '<app>/src' };
+    if (!KEBAB_CASE.test(options.name)) {
+        return refusal('invalid-name', dryRun, layer, options.name, unresolved);
+    }
+    // Validate the SAME effective value the composer will embed — an explicit
+    // publicApiName that isn't an identifier, or a slice name whose camelCase
+    // default is a reserved word (e.g. "class", "delete"), would otherwise
+    // silently produce syntactically broken TypeScript.
+    if (!isUsableSliceApiName(resolveSlicePublicApiName(options.name, options.publicApiName))) {
+        return refusal('invalid-public-api-name', dryRun, layer, options.name, unresolved);
+    }
+    // canonical FSD: a shared segment is named by purpose (ui, api, model, lib, config), never
+    // by what it contains.
+    if (layer === 'shared' && isEssenceSegmentName(options.name)) {
+        return refusal('segment-by-essence', dryRun, layer, options.name, unresolved);
+    }
+    // --segments: a shared segment holds no segments; elsewhere each
+    // name must be a directory-safe name by purpose, like the shared generator's own names.
+    const segments = Array.from(new Set(options.segments ?? []));
+    if (segments.length > 0 && layer === 'shared') {
+        return refusal('segments-on-shared', dryRun, layer, options.name, unresolved);
+    }
+    const badSegment = segments.find((segment) => !SEGMENT_NAME_PATTERN.test(segment));
+    if (badSegment !== undefined)
+        return refusal('invalid-segment', dryRun, layer, options.name, unresolved, { detail: badSegment });
+    const essenceSegment = segments.find((segment) => isEssenceSegmentName(segment));
+    if (essenceSegment !== undefined)
+        return refusal('segment-by-essence', dryRun, layer, options.name, unresolved, { detail: essenceSegment });
+    const app = resolveFrontendApp(tree, options.project);
+    if (app.kind === 'not-found')
+        return refusal('project-not-found', dryRun, layer, options.name, { project: app.project, sourceRoot: unresolved.sourceRoot });
+    if (app.kind === 'ambiguous')
+        return refusal('ambiguous-frontend', dryRun, layer, options.name, unresolved, { candidates: app.candidates });
+    if (app.kind === 'invalid-project-json')
+        return refusal('invalid-project-json', dryRun, layer, options.name, unresolved, { detail: app.detail });
+    if (app.kind === 'none')
+        return refusal('no-frontend-app', dryRun, layer, options.name, unresolved);
+    // The layer directory is created with its first slice (canonical FSD) — add-fsd-lite makes
+    // no folders. tree.write creates every missing parent.
+    const config = readToolkitConfig(tree);
+    const frontend = resolveFrontendForApp(options.frontend, config, app.root, tree);
+    const layerDir = layerDirFor(layer, app.sourceRoot, frontend);
+    const locale = resolveLocaleOption(options.locale, config);
+    const plan = composeSlice({
+        layer,
+        name: options.name,
+        publicApiName: resolveSlicePublicApiName(options.name, options.publicApiName),
+        locale,
+        sourceRoot: app.sourceRoot,
+        layerDirName: layerDirNameFor(layer, frontend),
+        segments,
+    });
+    const action = computeSliceAction(tree, plan);
+    if (action === 'created' && !dryRun) {
+        for (const file of plan.files)
+            tree.write(file.filePath, file.content);
+    }
+    return {
+        dryRun,
+        layer,
+        name: options.name,
+        project: app.project,
+        layerDir,
+        directory: plan.directory,
+        publicApiName: plan.publicApiName,
+        refused: false,
+        refusalReason: null,
+        action,
+        files: plan.files,
+    };
+}

package/dist/generators/slice/files/index/index.ts.template

@@ -0,0 +1,14 @@
+/**
+<% if (locale === 'ko') { -%>
+ * "<%- name %>"의 공개 API ("<%- layer %>" 레이어, FSD).
+ *
+ * 다른 슬라이스/레이어가 import할 수 있는 유일한 진입점입니다 — 밖으로 노출할 것은 모두 여기서
+ * 재export하고, 내부 파일(model/, ui/, api/ …)은 밖에서 직접 import하지 않습니다.
+<% } else { -%>
+ * Public API of "<%- name %>" (the "<%- layer %>" layer, FSD).
+ *
+ * The only entry point other slices and layers may import — re-export everything exposed
+ * from here; internal files (model/, ui/, api/ …) are never imported from outside.
+<% } -%>
+ */
+export { <%- publicApiName %> } from '<%- modulePath %>';

package/dist/generators/slice/files/module/__name__.spec.ts.template

@@ -0,0 +1,11 @@
+import { <%- publicApiName %> } from './<%- name %>.js';
+
+describe('<%- name %>', () => {
+<% if (locale === 'ko') { -%>
+  it('스캐폴드된 스텁을 호출할 수 있다 (실제 assertion으로 교체하세요)', () => {
+<% } else { -%>
+  it('is scaffolded and callable (replace with real assertions)', () => {
+<% } -%>
+    expect(() => <%- publicApiName %>()).not.toThrow();
+  });
+});

package/dist/generators/slice/files/module/__name__.ts.template

@@ -0,0 +1,11 @@
+<% if (locale === 'ko') { -%>
+// TODO: "<%- name %>"의 실제 동작을 구현하세요.
+export function <%- publicApiName %>(): void {
+  // TODO: 이 스텁 본문을 실제 구현으로 교체하세요.
+}
+<% } else { -%>
+// TODO: implement the real behavior of "<%- name %>".
+export function <%- publicApiName %>(): void {
+  // TODO: replace this stub body with the real implementation.
+}
+<% } -%>

package/dist/generators/slice/files/segment/index.ts.template

@@ -0,0 +1,20 @@
+<%
+const purposes = locale === 'ko'
+  ? { ui: '이 슬라이스의 컴포넌트·뷰·스타일', model: '이 슬라이스의 상태·비즈니스 로직·타입', api: '이 슬라이스의 요청과 데이터 매퍼', lib: '이 슬라이스 안에서만 쓰는 헬퍼', config: '이 슬라이스의 상수와 플래그' }
+  : { ui: 'components, views and styles of this slice', model: 'state, business logic and types of this slice', api: 'requests and data mappers of this slice', lib: 'helpers used only inside this slice', config: 'constants and flags of this slice' };
+const purpose = purposes[segment] ? ` — ${purposes[segment]}` : '';
+-%>
+/**
+<% if (locale === 'ko') { -%>
+ * "<%- name %>" 슬라이스의 "<%- segment %>" 세그먼트<%- purpose %>.
+ *
+ * 슬라이스 내부용입니다: 같은 슬라이스의 파일에서만 import하고(예: `../<%- segment %>`), 다른 슬라이스는
+ * 이 슬라이스의 index.ts를 통해서만 접근합니다. 밖으로 노출할 것은 index.ts에서 재export하세요.
+<% } else { -%>
+ * The "<%- segment %>" segment of the "<%- name %>" slice<%- purpose %>.
+ *
+ * Internal to the slice: import it from the slice's own files only (e.g. `../<%- segment %>`); other
+ * slices go through this slice's index.ts. Re-export from index.ts whatever should be public.
+<% } -%>
+ */
+export {};

package/dist/generators/slice/render.js

@@ -0,0 +1,70 @@
+const ACTION_LINES = {
+    created: 'created',
+    unchanged: 'unchanged (already matches the generated content)',
+    skipped: 'skipped — a slice with this name already exists with different content',
+};
+export function renderSliceReport(report) {
+    const lines = [];
+    const label = `${report.layer} "${report.name}"`;
+    if (report.refused) {
+        lines.push(`${label}: refused — nothing was written.`);
+        lines.push('');
+        if (report.refusalReason === 'invalid-name') {
+            lines.push(`  "${report.name}" is not a valid kebab-case slice name.`);
+            lines.push('  Use lowercase letters, digits, and single hyphens, starting with a letter (e.g. "add-to-cart").');
+        }
+        else if (report.refusalReason === 'invalid-public-api-name') {
+            lines.push('  The public API name is not a usable JavaScript identifier (or is a reserved word).');
+            lines.push('  Pass --publicApiName with a valid identifier, e.g. "addToCart" (this also happens when');
+            lines.push('  the slice name camelCases into a reserved word, like "class" or "delete").');
+        }
+        else if (report.refusalReason === 'project-not-found') {
+            lines.push(`  --project=${report.project} names no project in this workspace.`);
+        }
+        else if (report.refusalReason === 'ambiguous-frontend') {
+            lines.push('  More than one frontend app was found — rerun with --project=<one of them>:');
+            for (const name of report.candidates ?? [])
+                lines.push(`    - ${name}`);
+        }
+        else if (report.refusalReason === 'invalid-project-json') {
+            lines.push(`  A project.json could not be parsed (${report.detail ?? 'unknown'}) — fix it, then rerun.`);
+        }
+        else if (report.refusalReason === 'no-frontend-app') {
+            lines.push('  The workspace has no frontend application to hold FSD layers — create one, or pass --project.');
+        }
+        else if (report.refusalReason === 'invalid-segment') {
+            lines.push(`  --segments: "${report.detail ?? ''}" is not a valid segment name.`);
+            lines.push('  Use lowercase letters, digits, and single hyphens, starting with a letter (e.g. ui, api, lib).');
+        }
+        else if (report.refusalReason === 'segments-on-shared') {
+            lines.push('  --segments does not apply to shared: a shared segment holds no segments of its own.');
+            lines.push('  Run the generator once per segment instead (e.g. --name=ui, then --name=api).');
+        }
+        else {
+            const offender = report.detail ?? report.name;
+            lines.push(`  "${offender}" names what a segment contains, not what it is for.`);
+            lines.push('  Canonical FSD names segments by purpose — ui, api, model, lib, config — so the code stays');
+            lines.push('  findable by what it does (e.g. a date helper lives in shared/lib, a Button in shared/ui).');
+        }
+        return lines.join('\n');
+    }
+    if (report.dryRun) {
+        lines.push('dry-run — no files were written.');
+        lines.push('');
+    }
+    lines.push(`${label}: ${ACTION_LINES[report.action]}`);
+    if (report.action === 'skipped') {
+        lines.push(`  ${report.directory} already exists and does not exactly match the generated content.`);
+        lines.push('  Pick a new slice name (a name collision is a signal to rename, not to merge)');
+        lines.push('  — or remove the existing directory manually first if you intended to replace it.');
+        return lines.join('\n');
+    }
+    if (report.dryRun) {
+        for (const file of report.files) {
+            lines.push('');
+            lines.push(`${file.filePath}:`);
+            lines.push(file.content);
+        }
+    }
+    return lines.join('\n');
+}