fimo 0.7.0-experimental.2 → 0.7.0-staging.1

package/dist/scripts/validate-schemas.test.js

@@ -0,0 +1,263 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { validateSchemas } from './validate-schemas';
+describe('validateSchemas', () => {
+    let scratch = null;
+    afterEach(() => {
+        if (scratch) {
+            rmSync(scratch, { recursive: true, force: true });
+            scratch = null;
+        }
+    });
+    function writeProject(schemas) {
+        scratch = mkdtempSync(join(tmpdir(), 'validate-schemas-'));
+        mkdirSync(join(scratch, 'src/schemas'), { recursive: true });
+        for (const [fileName, schema] of Object.entries(schemas)) {
+            writeFileSync(join(scratch, 'src/schemas', fileName), typeof schema === 'string' ? schema : JSON.stringify(schema, null, 2));
+        }
+        return scratch;
+    }
+    it('accepts a valid schema', () => {
+        const cwd = writeProject({
+            'Author.json': {
+                uid: 'Author',
+                name: 'Authors',
+                fields: {
+                    name: { type: 'string' },
+                },
+            },
+            'BlogPost.json': {
+                uid: 'BlogPost',
+                name: 'Blog Posts',
+                fields: {
+                    title: { type: 'string' },
+                    body: { type: 'richtext' },
+                    coverImage: { type: 'media' },
+                    featured: { type: 'boolean' },
+                    author: { type: 'reference', target: 'Author' },
+                },
+            },
+        });
+        expect(validateSchemas({ cwd })).toEqual({ errors: [], schemasChecked: 2 });
+    });
+    it('accepts self-referential reference fields', () => {
+        const cwd = writeProject({
+            'Item.json': {
+                uid: 'Item',
+                name: 'Items',
+                fields: {
+                    title: { type: 'string' },
+                    parent: { type: 'reference', target: 'Item' },
+                },
+            },
+        });
+        expect(validateSchemas({ cwd })).toEqual({ errors: [], schemasChecked: 1 });
+    });
+    it('accepts a non-localized schema policy', () => {
+        const cwd = writeProject({
+            'Author.json': {
+                uid: 'Author',
+                name: 'Authors',
+                i18n: { enabled: false },
+                fields: { name: { type: 'string' } },
+            },
+        });
+        expect(validateSchemas({ cwd })).toEqual({ errors: [], schemasChecked: 1 });
+    });
+    it('rejects a non-boolean singleton policy', () => {
+        const cwd = writeProject({
+            'Settings.json': {
+                uid: 'Settings',
+                name: 'Settings',
+                isSingleton: 'yes',
+                fields: {},
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toEqual([expect.objectContaining({ rule: 'schemas/singleton' })]);
+    });
+    it.each([true, { enabled: 'no' }, { enabled: false, fallback: 'en' }, { fallback: 'en' }])('rejects an invalid schema-level i18n policy %#', (i18n) => {
+        const cwd = writeProject({
+            'Author.json': {
+                uid: 'Author',
+                name: 'Authors',
+                i18n,
+                fields: { name: { type: 'string' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/i18n' });
+    });
+    it('returns no errors when the schemas directory does not exist', () => {
+        scratch = mkdtempSync(join(tmpdir(), 'validate-schemas-'));
+        expect(validateSchemas({ cwd: scratch })).toEqual({ errors: [], schemasChecked: 0 });
+    });
+    it('rejects reserved field names like slug', () => {
+        const cwd = writeProject({
+            'TeamMember.json': {
+                uid: 'TeamMember',
+                name: 'Team Members',
+                fields: {
+                    name: { type: 'string' },
+                    slug: { type: 'string' },
+                },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/reserved-field', file: 'src/schemas/TeamMember.json' });
+        expect(errors[0].message).toContain('"slug" is reserved');
+        expect(errors[0].message).toContain('entry data');
+    });
+    it('rejects every reserved metadata name', () => {
+        const cwd = writeProject({
+            'Bad.json': {
+                uid: 'Bad',
+                name: 'Bad',
+                fields: Object.fromEntries(['id', 'entryId', 'documentId', 'slug', 'locale', 'createdAt', 'updatedAt', '__fimo'].map((name) => [
+                    name,
+                    { type: 'string' },
+                ])),
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(8);
+        expect(errors.every((err) => err.rule === 'schemas/reserved-field')).toBe(true);
+    });
+    it('rejects unsupported field types', () => {
+        const cwd = writeProject({
+            'Product.json': {
+                uid: 'Product',
+                name: 'Products',
+                fields: { price: { type: 'decimal' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/field-type' });
+        expect(errors[0].message).toContain('"decimal"');
+        expect(errors[0].message).toContain('string, richtext, media');
+    });
+    it('rejects reference fields without a valid target', () => {
+        const cwd = writeProject({
+            'Post.json': {
+                uid: 'Post',
+                name: 'Posts',
+                fields: { author: { type: 'reference' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/reference-target' });
+    });
+    it('rejects reference fields targeting a missing local schema', () => {
+        const cwd = writeProject({
+            'Post.json': {
+                uid: 'Post',
+                name: 'Posts',
+                fields: { author: { type: 'reference', target: 'Author' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/reference-target' });
+        expect(errors[0].message).toContain('unknown schema "Author"');
+    });
+    it('rejects reference-only properties on scalar fields', () => {
+        const cwd = writeProject({
+            'Post.json': {
+                uid: 'Post',
+                name: 'Posts',
+                fields: { author: { type: 'string', target: 'Author' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/reference-shape' });
+    });
+    it('rejects schema uid names that cannot be used as content type identifiers', () => {
+        const cwd = writeProject({
+            'blog-post.json': {
+                uid: 'blog-post',
+                name: 'Blog Posts',
+                fields: { title: { type: 'string' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/type-name' });
+    });
+    it('rejects field names that cannot be used in generated source paths', () => {
+        const cwd = writeProject({
+            'Page.json': {
+                uid: 'Page',
+                name: 'Pages',
+                fields: { 'hero-title': { type: 'string' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/field-name' });
+    });
+    it('rejects field-level i18n settings', () => {
+        const cwd = writeProject({
+            'Page.json': {
+                uid: 'Page',
+                name: 'Pages',
+                fields: { title: { type: 'string', i18n: true } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/field-i18n' });
+    });
+    it('rejects reference-level locale settings', () => {
+        const cwd = writeProject({
+            'Page.json': {
+                uid: 'Page',
+                name: 'Pages',
+                fields: { parent: { type: 'reference', target: 'Page', localized: true } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/field-i18n' });
+        expect(errors[0].message).toContain('"localized"');
+    });
+    it('rejects a uid that does not match the file name', () => {
+        const cwd = writeProject({
+            'TeamMember.json': {
+                uid: 'Member',
+                name: 'Team Members',
+                fields: { name: { type: 'string' } },
+            },
+        });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/uid' });
+    });
+    it('rejects missing uid, name, and fields', () => {
+        const cwd = writeProject({ 'Empty.json': {} });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors.map((err) => err.rule)).toEqual(['schemas/uid', 'schemas/name', 'schemas/fields']);
+    });
+    it('reports invalid JSON', () => {
+        const cwd = writeProject({ 'Broken.json': '{ not json' });
+        const { errors } = validateSchemas({ cwd });
+        expect(errors).toHaveLength(1);
+        expect(errors[0]).toMatchObject({ rule: 'schemas/parse' });
+    });
+    it('validates multiple files and counts them', () => {
+        const cwd = writeProject({
+            'Good.json': { uid: 'Good', name: 'Good', fields: { title: { type: 'string' } } },
+            'Bad.json': { uid: 'Bad', name: 'Bad', fields: { slug: { type: 'string' } } },
+        });
+        const result = validateSchemas({ cwd });
+        expect(result.schemasChecked).toBe(2);
+        expect(result.errors).toHaveLength(1);
+        expect(result.errors[0].file).toBe('src/schemas/Bad.json');
+    });
+});

package/package.json

@@ -1,16 +1,14 @@
 {
   "name": "fimo",
-  "version": "0.7.0-experimental.2",
+  "version": "0.7.0-staging.1",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "bin": {
     "fimo": "dist/cli/index.js"
   },
   "files": [
     "dist/",
-    "!dist/**/*.d.ts.map",
     "assets/",
-    "scripts/postinstall.mjs",
-    "scripts/lib/postinstall-onboarding.mjs",
+    "scripts/",
     "templates/",
     "README.md",
     "release.json"
@@ -49,7 +47,7 @@
   "scripts": {
     "build": "pnpm run clean && tsc -b tsconfig.json && chmod +x dist/cli/index.js",
     "build:bundle": "node scripts/bundle-cli.mjs",
-    "check:types": "tsc -b tsconfig.json && tsc -p tsconfig.test.json",
+    "check:types": "tsc -b tsconfig.json",
     "start": "tsx src/cli/index.ts",
     "install-cli": "pnpm build && node scripts/install-cli.mjs",
     "publish:npm": "node scripts/publish-npm.mjs",
@@ -62,16 +60,23 @@
     "clean": "rm -rf dist *.tsbuildinfo"
   },
   "dependencies": {
+    "@clack/core": "^1.2.0",
+    "@clack/prompts": "^1.2.0",
     "@rollup/pluginutils": "^5.1.0",
+    "agent-install": "^0.0.5",
+    "better-auth": "1.4.18",
     "change-case": "^5.4.4",
+    "cheerio": "^1.0.0",
+    "commander": "^13.1.0",
     "eta": "^3.5.0",
+    "lucide-react": "^0.577.0",
+    "open": "^10.1.2",
     "oxc-parser": "^0.118.0",
     "react-error-boundary": "^6.0.0",
+    "yaml": "2.8.2",
     "zod": "4.1.8"
   },
   "devDependencies": {
-    "@clack/core": "^1.2.0",
-    "@clack/prompts": "^1.2.0",
     "@fimo/agents-bundle": "workspace:*",
     "@fimo/api-contracts": "workspace:*",
     "@fimo/cli-kit": "workspace:*",
@@ -80,12 +85,7 @@
     "@types/node": "^22.15.29",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "agent-install": "^0.0.5",
-    "better-auth": "1.4.18",
-    "cheerio": "^1.0.0",
-    "commander": "^13.1.0",
     "esbuild": "^0.25.10",
-    "open": "^10.1.2",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
     "react-router": "^7.15.1",
@@ -93,8 +93,7 @@
     "typescript": "5.9.2",
     "vite": "^8.0.13",
     "vitest": "^4.1.6",
-    "wrangler": "^4.83.0",
-    "yaml": "2.8.2"
+    "wrangler": "^4.83.0"
   },
   "peerDependencies": {
     "@tanstack/react-query": "^5.80.6",
@@ -103,23 +102,6 @@
     "react-router": "^7.0.0 || ^8.0.0",
     "vite": "^7.0.0 || ^8.0.0"
   },
-  "peerDependenciesMeta": {
-    "@tanstack/react-query": {
-      "optional": true
-    },
-    "react": {
-      "optional": true
-    },
-    "react-dom": {
-      "optional": true
-    },
-    "react-router": {
-      "optional": true
-    },
-    "vite": {
-      "optional": true
-    }
-  },
   "engines": {
     "node": ">=20.12.0"
   }

package/scripts/add-ext.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+// Rewrite relative imports to add `.js` extensions (required by Node ESM).
+// Idempotent. Preserves all other code.
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { extname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = resolve(fileURLToPath(import.meta.url), '..');
+const ROOTS = process.argv.slice(2).map((p) => resolve(p));
+
+const IMPORT_RE = /(from\s+|import\s*\(\s*)(['"])(\.\.?\/[^'"\s]+?)\2/g;
+
+function walk(dir, out) {
+  for (const name of readdirSync(dir)) {
+    if (['node_modules', 'dist', '.git'].includes(name)) continue;
+    const p = `${dir}/${name}`;
+    const st = statSync(p);
+    if (st.isDirectory()) walk(p, out);
+    else if (/\.(ts|tsx|mts|mjs)$/.test(name) && !name.endsWith('.d.ts')) out.push(p);
+  }
+}
+
+function rewriteOne(filePath) {
+  const src = readFileSync(filePath, 'utf-8');
+  const dir = filePath.split('/').slice(0, -1).join('/');
+  let mutated = false;
+  const out = src.replace(IMPORT_RE, (match, lead, quote, spec) => {
+    const ext = extname(spec);
+    if (ext) return match;
+    const candidate = resolve(dir, spec);
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      mutated = true;
+      return `${lead}${quote}${spec}/index.js${quote}`;
+    }
+    mutated = true;
+    return `${lead}${quote}${spec}.js${quote}`;
+  });
+  if (mutated) {
+    writeFileSync(filePath, out);
+    console.log(`updated ${filePath.slice(HERE.length - 7)}`);
+  }
+}
+
+const files = [];
+for (const r of ROOTS) walk(r, files);
+for (const f of files) rewriteOne(f);
+console.log(`[add-ext] processed ${files.length} files`);

package/scripts/bump-version.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+// Bumps the Fimo CLI version in apps/cli/package.json — NO git tag, NO commit.
+//
+// Under the branch-driven release model the version lives in
+// apps/cli/package.json and you bump it in a PR. CI creates the
+// `cli@<version>` git tag when it publishes `@latest` on a `production`
+// merge, so this script must NOT create a tag — that would collide with
+// CI's tag-guard (the publish would skip, thinking the version already
+// shipped).
+//
+// Usage:
+//   pnpm -F fimo release:bump patch
+//   pnpm -F fimo release:bump minor
+//   pnpm -F fimo release:bump major
+//   pnpm -F fimo release:bump 1.2.3            # explicit version
+//
+// After bumping, commit the change in your PR. Merging it through to
+// `production` is what publishes `@latest` and creates the tag.
+
+import { spawnSync } from 'node:child_process';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI_ROOT = resolve(HERE, '..');
+
+const VALID_INCREMENTS = new Set(['major', 'minor', 'patch', 'premajor', 'preminor', 'prepatch', 'prerelease']);
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error(
+    '[cli/bump] usage: pnpm -F fimo release:bump <patch|minor|major|premajor|preminor|prepatch|prerelease|X.Y.Z> [--preid <id>]'
+  );
+  process.exit(1);
+}
+
+const increment = args[0];
+const isExplicitVersion = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/.test(increment);
+if (!VALID_INCREMENTS.has(increment) && !isExplicitVersion) {
+  console.error(
+    `[cli/bump] invalid increment "${increment}". expected one of ${[...VALID_INCREMENTS].join('|')} or an explicit X.Y.Z.`
+  );
+  process.exit(1);
+}
+
+// Bump package.json ONLY — `--no-git-tag-version` skips both the commit and
+// the tag. CI owns the `cli@<version>` tag (created on the @latest publish).
+// Use pnpm (not npm) — npm chokes on the `workspace:*` devDeps.
+const versionArgs = ['version', '--no-git-tag-version', ...args];
+console.log(`[cli/bump] $ pnpm ${versionArgs.join(' ')}`);
+const result = spawnSync('pnpm', versionArgs, { cwd: CLI_ROOT, stdio: 'inherit' });
+if (result.status !== 0) {
+  console.error(`[cli/bump] pnpm version failed (exit ${result.status}).`);
+  process.exit(result.status ?? 1);
+}
+
+console.log('[cli/bump] bumped apps/cli/package.json (no tag, no commit).');
+console.log('[cli/bump] commit it in your PR — merging to `production` publishes @latest + tags it.');

package/scripts/bundle-cli.mjs

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// Bundles the Fimo CLI binary into a single self-contained ESM file at
+// `dist/cli/index.js`, overwriting the per-file tsc output.
+//
+// Scope:
+//  - Only the `bin` entry (`src/cli/index.ts`) is bundled. The subpath
+//    exports (`fimo/ui`, `fimo/seo`, `fimo/app`, `fimo/vite`,
+//    `fimo/config/react-router`) keep their multi-file tsc output under
+//    `dist/runtime/` and `dist/build/`.
+//  - Native deps are kept external (`oxc-parser` has a Rust addon) so they
+//    resolve at runtime from the published `dependencies`.
+//  - All other deps reachable from `src/cli/index.ts` are inlined.
+//
+// This script assumes `tsc -b` has already produced the rest of `dist/`. Run
+// `pnpm -F fimo build` first, or use the `prepublishOnly` chain.
+//
+// Usage:
+//   node scripts/bundle-cli.mjs
+
+import { readFileSync, rmSync, writeFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { build } from 'esbuild';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI_ROOT = resolve(HERE, '..');
+const ENTRY = resolve(CLI_ROOT, 'src/cli/index.ts');
+const OUTFILE = resolve(CLI_ROOT, 'dist/cli/index.js');
+
+// Native or otherwise non-bundlable runtime deps. Keep them in the published
+// `dependencies` so `npm install -g fimo` pulls them in transitively.
+const EXTERNAL = [
+  'oxc-parser', // Rust-backed native parser
+  'fsevents', // macOS-only native .node addon; chokidar require()s it behind a try/catch
+];
+
+const pkg = JSON.parse(readFileSync(resolve(CLI_ROOT, 'package.json'), 'utf8'));
+
+console.log(`[cli/bundle] entry:   ${ENTRY}`);
+console.log(`[cli/bundle] outfile: ${OUTFILE}`);
+console.log(`[cli/bundle] external: ${EXTERNAL.join(', ')}`);
+
+const result = await build({
+  entryPoints: [ENTRY],
+  outfile: OUTFILE,
+  bundle: true,
+  platform: 'node',
+  target: 'node20',
+  format: 'esm',
+  // Esbuild promotes the source's `#!/usr/bin/env node` shebang to line 1 of
+  // the output, then prepends this banner. Some bundled deps (notably
+  // `commander`) are CJS and call `require('node:events')` etc. internally;
+  // esbuild wraps those with its own `__require` helper which doesn't know
+  // about Node built-ins. Injecting `createRequire` here gives the bundled
+  // CJS a working `require()` against the real Node resolver.
+  banner: {
+    js: "import { createRequire as __fimoCreateRequire } from 'node:module';\nconst require = __fimoCreateRequire(import.meta.url);",
+  },
+  // Mark native runtime deps as external; everything else inlines.
+  external: EXTERNAL,
+  // Inline node_modules deps reachable from the entry. Built-ins
+  // (node:fs, etc.) are externalized automatically by `platform=node`.
+  packages: 'bundle',
+  // Resolve .ts / .tsx during the bundling pass (we're reading source, not
+  // the tsc output).
+  resolveExtensions: ['.ts', '.tsx', '.mjs', '.js'],
+  // ESM emit requires ESM-style imports for built-ins.
+  mainFields: ['module', 'main'],
+  conditions: ['node', 'import', 'default'],
+  // Keep file names stable in the bundled output for clearer stack traces.
+  keepNames: true,
+  // Source map is overkill in the published tarball; skip for v1.
+  sourcemap: false,
+  // Minification trades readability for ~30% size; skip - the bundle stays
+  // human-grep-able which helps debugging field issues. Revisit if size
+  // becomes a problem.
+  minify: false,
+  // Surface every warning so we don't silently produce a broken bundle.
+  logLevel: 'info',
+  metafile: true,
+});
+
+// Stamp the version + bundled marker into a sidecar so `release.json` /
+// future tooling can detect bundled artifacts without re-parsing the bundle.
+const meta = {
+  bundled: true,
+  bundler: 'esbuild',
+  bundledAt: new Date().toISOString(),
+  cliVersion: pkg.version,
+  external: EXTERNAL,
+};
+writeFileSync(resolve(CLI_ROOT, 'dist/cli/bundle.json'), JSON.stringify(meta, null, 2) + '\n');
+
+// Clean up the per-file tsc artifacts under `dist/cli/` that the bundle has
+// now subsumed - anything except `index.js` and the sidecar. Subpath exports
+// live under `dist/runtime/` and `dist/build/`, which stay untouched.
+const inputs = Object.keys(result.metafile.inputs);
+console.log(`[cli/bundle] inlined ${inputs.length} modules`);
+
+const distCli = resolve(CLI_ROOT, 'dist/cli');
+const { readdirSync } = await import('node:fs');
+function rmExceptIndex(dir) {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const full = resolve(dir, entry.name);
+    if (dir === distCli && (entry.name === 'index.js' || entry.name === 'bundle.json')) {
+      continue;
+    }
+    rmSync(full, { recursive: true, force: true });
+  }
+}
+rmExceptIndex(distCli);
+
+// Make the bin executable. npm chmods bin files on `npm install -g`
+// regardless, but a properly-permissioned tarball is the right hygiene
+// AND it makes the local-link flow (where the user's checkout is
+// symlinked into ~/.fimovm/linked/<alias>) work without a follow-up
+// chmod step.
+import { chmodSync } from 'node:fs';
+chmodSync(OUTFILE, 0o755);
+
+const bytes = statSync(OUTFILE).size;
+console.log(`[cli/bundle] done. ${(bytes / 1024).toFixed(1)} KB written to ${OUTFILE}`);

package/scripts/install-cli.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+// Creates a `fimo` symlink in ~/.local/bin/ pointing at the built CLI entry
+// so `fimo <command>` works from any directory on the machine.
+import { chmodSync, existsSync, mkdirSync, symlinkSync, unlinkSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const CLI_ROOT = resolve(HERE, '..');
+const ENTRY = resolve(CLI_ROOT, 'dist', 'cli', 'index.js');
+
+if (!existsSync(ENTRY)) {
+  console.error(`[cli/install] Built entry not found at ${ENTRY}. Run \`pnpm -F cli build\` first.`);
+  process.exit(1);
+}
+
+const BIN_DIR = resolve(homedir(), '.local', 'bin');
+const LINK = resolve(BIN_DIR, 'fimo');
+
+mkdirSync(BIN_DIR, { recursive: true });
+chmodSync(ENTRY, 0o755);
+if (existsSync(LINK)) {
+  unlinkSync(LINK);
+}
+symlinkSync(ENTRY, LINK);
+
+console.log(`[cli/install] Linked ${LINK} → ${ENTRY}`);
+
+const pathDirs = (process.env.PATH ?? '').split(':');
+if (!pathDirs.includes(BIN_DIR)) {
+  console.log('');
+  console.log(`⚠  ${BIN_DIR} is not on your PATH.`);
+  console.log('   Add this to your shell rc (~/.zshrc, ~/.bashrc, ...):');
+  console.log(`     export PATH="$HOME/.local/bin:$PATH"`);
+}