@grimoire-rs/indexer 0.2.1 → 0.3.0

package/dist/cli/dev.js

@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+// `grim-indexer dev` — serve this index locally, so a change to an entry, the
+// branding, or the custom CSS can be looked at before it is pushed. It renders
+// through the same code path `build` does, so what is on screen is what the
+// deploy will publish.
+import path from "node:path";
+import { CliError, EXIT } from "./exit.js";
+import { resolveOutDir } from "./out_dir.js";
+/**
+ * A bad `--port` is a usage error (64), like every other bad flag. Passed
+ * through unchecked it reached Astro as `NaN` and surfaced as a raw zod issue
+ * dump naming no flag at all, exiting 1.
+ */
+function resolvePort(port) {
+    if (port === undefined)
+        return undefined;
+    const value = Number(port);
+    if (!Number.isInteger(value) || value < 1 || value > 65535) {
+        throw new CliError(`--port ${JSON.stringify(port)}: must be a port number (1-65535)`, EXIT.usage);
+    }
+    return value;
+}
+export async function dev(root, flags) {
+    const rootDir = path.resolve(root);
+    const outDir = resolveOutDir(rootDir, flags.outDir);
+    const port = resolvePort(flags.port);
+    const [{ loadConfig }, { compileIndex }, { devSite }] = await Promise.all([
+        import("../config.js"),
+        import("../data/index.js"),
+        import("../renderer/index.js"),
+    ]);
+    const config = await loadConfig(rootDir);
+    const { count, namespaces } = await compileIndex({ root: rootDir, outDir });
+    const server = await devSite({ root: rootDir, outDir, config, port });
+    console.log(`\n  ${server.url}\n`);
+    console.log(`  ${count} package(s) across ${namespaces.length} namespace(s)`);
+    // `index.config.json` is read once, at boot, and baked into the bundle — the
+    // same thing a build does. Say so, or an edit that appears to do nothing
+    // reads as a bug in the renderer.
+    console.log("  editing index/ or index.config.json? restart to pick it up\n");
+    // The server owns the process from here. Astro's dev server keeps the event
+    // loop alive on its own, but the promise is what stops `run` from returning
+    // and letting the CLI set an exit code out from under it.
+    await new Promise((resolve) => {
+        for (const signal of ["SIGINT", "SIGTERM"]) {
+            process.on(signal, () => {
+                void server
+                    .stop()
+                    .catch(() => { })
+                    .finally(resolve);
+            });
+        }
+    });
+    return EXIT.ok;
+}
+//# sourceMappingURL=dev.js.map

package/dist/cli/dev.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dev.js","sourceRoot":"","sources":["../../src/cli/dev.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,sCAAsC;AAEtC,8EAA8E;AAC9E,+EAA+E;AAC/E,4EAA4E;AAC5E,uBAAuB;AACvB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAiB,MAAM,WAAW,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAO7C;;;;GAIG;AACH,SAAS,WAAW,CAAC,IAAwB;IAC3C,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACzC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;IAC3B,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,KAAK,EAAE,CAAC;QAC3D,MAAM,IAAI,QAAQ,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,mCAAmC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,GAAG,CAAC,IAAY,EAAE,KAAe;IACrD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACpD,MAAM,IAAI,GAAG,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAErC,MAAM,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QACxE,MAAM,CAAC,cAAc,CAAC;QACtB,MAAM,CAAC,kBAAkB,CAAC;QAC1B,MAAM,CAAC,sBAAsB,CAAC;KAC/B,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,MAAM,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAEtE,OAAO,CAAC,GAAG,CAAC,OAAO,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC;IACnC,OAAO,CAAC,GAAG,CAAC,KAAK,KAAK,sBAAsB,UAAU,CAAC,MAAM,eAAe,CAAC,CAAC;IAC9E,6EAA6E;IAC7E,yEAAyE;IACzE,kCAAkC;IAClC,OAAO,CAAC,GAAG,CAAC,gEAAgE,CAAC,CAAC;IAE9E,4EAA4E;IAC5E,4EAA4E;IAC5E,0DAA0D;IAC1D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAClC,KAAK,MAAM,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAU,EAAE,CAAC;YACpD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;gBACtB,KAAK,MAAM;qBACR,IAAI,EAAE;qBACN,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC;qBACf,OAAO,CAAC,OAAO,CAAC,CAAC;YACtB,CAAC,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC,EAAE,CAAC;AACjB,CAAC"}

package/dist/cli/init.d.ts

@@ -1,5 +1,6 @@
+import { type Forge } from "../ci.js";
 import { type ExitCode } from "./exit.js";
-export type Forge = "github" | "gitlab" | "both";
+export type { Forge };
 /** Everything `init` needs to render the scaffold. Flags and prompts both resolve into this. */
 export interface InitAnswers {
     name: string;
@@ -10,6 +11,7 @@ export interface InitAnswers {
     logo: string;
     forge: Forge;
     git: boolean;
+    install: boolean;
     withSkills: boolean;
     /** This repo's own https URL — the announce target. `""` when nothing could derive it. */
     repoUrl: string;
@@ -25,6 +27,7 @@ export interface InitFlags {
     logo?: string;
     forge?: Forge;
     git?: boolean;
+    install?: boolean;
     withSkills?: boolean;
     repoUrl?: string;
     force?: boolean;
@@ -38,6 +41,8 @@ export interface InitResult {
         outcome: FileOutcome;
     }>;
     gitInitialized: boolean;
+    /** Whether `npm install` ran and wrote a lock. */
+    installed: boolean;
 }
 export declare function init(dir: string, flags: InitFlags, version: string): Promise<ExitCode>;
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAaA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAwB1D,MAAM,MAAM,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjD,gGAAgG;AAChG,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;IACb,UAAU,EAAE,OAAO,CAAC;IACpB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACrD,cAAc,EAAE,OAAO,CAAC;CACzB;AAubD,wBAAsB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAwB5F"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/cli/init.ts"],"names":[],"mappings":"AAYA,OAAO,EAA6D,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AAGjG,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAkB1D,YAAY,EAAE,KAAK,EAAE,CAAC;AAEtB,gGAAgG;AAChG,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,UAAU,EAAE,OAAO,CAAC;IACpB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,4CAA4C;AAC5C,MAAM,MAAM,WAAW,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,SAAS,CAAC;AAE9E,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,CAAC,CAAC;IACrD,cAAc,EAAE,OAAO,CAAC;IACxB,kDAAkD;IAClD,SAAS,EAAE,OAAO,CAAC;CACpB;AAopBD,wBAAsB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAmD5F"}

package/dist/cli/init.js

@@ -6,13 +6,11 @@
 import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 import * as prompts from "@clack/prompts";
+import { loadCiConfig, renderCi, resolveCi, staleCi } from "../ci.js";
+import { CONFIG_FILE } from "../config.js";
+import { fromTemplate } from "../templates.js";
 import { CliError, EXIT } from "./exit.js";
-/** Scaffold templates ship beside `dist/`, so this resolves identically from `src/cli/` and `dist/cli/`. */
-const TEMPLATE_DIR = fileURLToPath(new URL("../../templates/", import.meta.url));
-/** `{{name}}`, but never GitHub Actions' `${{ ... }}` — hence the `$` lookbehind. */
-const PLACEHOLDER = /(?<!\$)\{\{\s*([A-Za-z_]\w*)\s*\}\}/g;
 const NAME_RE = /^[a-z0-9][a-z0-9._-]*$/;
 /**
  * What `[announce]` gets when nothing knew this repo's URL. It is not a
@@ -39,23 +37,6 @@ function titleCase(name) {
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
         .join(" ");
 }
-function readTemplate(rel) {
-    const file = path.join(TEMPLATE_DIR, rel);
-    try {
-        return fs.readFileSync(file, "utf8");
-    }
-    catch {
-        throw new CliError(`scaffold template ${rel} is missing from ${TEMPLATE_DIR} — the installed package is incomplete`, EXIT.unavailable);
-    }
-}
-function render(template, vars, rel) {
-    return template.replace(PLACEHOLDER, (match, key) => {
-        if (!(key in vars)) {
-            throw new CliError(`scaffold template ${rel} references unknown placeholder {{${key}}}`);
-        }
-        return vars[key];
-    });
-}
 /** Validate a URL the user typed. Returns the reason it is bad, or `null`. */
 function badUrl(value) {
     let url;
@@ -76,6 +57,12 @@ function badName(value) {
     }
     return null;
 }
+/** What `SiteConfig.logo` accepts — checked here so a typo fails now, not at build time. */
+function badLogo(value) {
+    if (value === "" || /^(\/|https?:\/\/)/i.test(value))
+        return null;
+    return "must be a site-root path (/logo.svg) or an http(s) URL";
+}
 /**
  * The target dir's `origin` remote as an https URL — set when the repo was
  * created on the forge and cloned before scaffolding into it. Any remote
@@ -92,6 +79,19 @@ function gitRemoteUrl(dir) {
     catch {
         return undefined; // no git, no repo, or no `origin`
     }
+    return normalizeRepoUrl(remote);
+}
+/**
+ * Reduce any repository URL to the https form the rest of this file derives
+ * from: Pages URL, forge, announce target and the site's own header link.
+ *
+ * Applied to `--repo-url` as well as to the git remote, because the obvious
+ * thing to paste into it is GitHub's clone box — `https://github.com/acme/idx.git`
+ * — and used verbatim that trailing `.git` became `https://acme.github.io/idx.git`
+ * as `site`, hence `/idx.git` as Astro's `base`, on a Pages deployment that
+ * serves `/idx`. Every link on the built site pointed one path segment wrong.
+ */
+function normalizeRepoUrl(remote) {
     const bare = remote.replace(/\.git$/, "");
     const scp = SCP_REMOTE.exec(bare);
     if (scp)
@@ -128,6 +128,89 @@ function repoUrlFromPages(baseUrl) {
     const project = url.pathname.split("/").filter(Boolean)[0] ?? url.hostname;
     return `https://${pages[2]}.com/${pages[1]}/${project}`;
 }
+/**
+ * Say out loud what was read off the git remote, and what could not be.
+ *
+ * Everything below is inferred rather than asked, and an inference nobody
+ * sees is one nobody checks — a wrong `site` is only noticed once the deploy
+ * serves 404s from a subpath that does not exist. The silences matter as much
+ * as the hits: a self-hosted forge can serve Pages from anywhere, so there is
+ * no URL to guess, and an unrecognised host is not evidence of GitHub.
+ */
+function reportDerivation(what) {
+    const say = (label, value) => console.log(`  ${label.padEnd(12)}${value}`);
+    if (!what.remoteUrl) {
+        say("no remote", "nothing to derive - set `site` in index.config.json yourself");
+        return;
+    }
+    say(what.fromRemote ? "from origin" : "repository", what.remoteUrl);
+    if (what.forge)
+        say("forge", what.forge);
+    if (what.forgeFallback) {
+        say("forge", "github (the host is neither github nor gitlab - pass --forge)");
+    }
+    if (what.baseUrl) {
+        say("site", what.baseUrl);
+    }
+    else {
+        say("site", "not derivable from this host - set `site` in index.config.json");
+    }
+}
+/**
+ * Which forge hosts `repoUrl`. Read off the host, so a self-hosted
+ * `gitlab.example.com` or `github.acme.internal` lands on the right pipeline
+ * without anyone having to answer a question about it. Anything unrecognised
+ * returns `undefined` and the prompt asks.
+ */
+function forgeFromRepoUrl(repoUrl) {
+    let host;
+    try {
+        host = new URL(repoUrl).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    if (host === "github.com" || host.startsWith("github."))
+        return "github";
+    if (host === "gitlab.com" || host.startsWith("gitlab."))
+        return "gitlab";
+    return undefined;
+}
+/**
+ * The Pages URL a forge serves `repoUrl` from — the inverse of
+ * [`repoUrlFromPages`], and the reason nobody has to know their own Pages URL
+ * to scaffold an index.
+ *
+ * `github.com/acme/idx` -> `https://acme.github.io/idx`, and the repository
+ * *named after* the Pages host is served from its root rather than a
+ * subpath. GitLab keeps everything below the top-level group in the path, so
+ * `gitlab.com/acme/team/idx` -> `https://acme.gitlab.io/team/idx`.
+ *
+ * Only the two public hosts are answered. A self-hosted instance can serve
+ * Pages from anywhere, and a custom domain is a fact this command cannot
+ * observe — both are why the value is a prompt default and not a decision.
+ */
+function pagesUrlFromRepo(repoUrl) {
+    let url;
+    try {
+        url = new URL(repoUrl);
+    }
+    catch {
+        return undefined;
+    }
+    const host = url.hostname.toLowerCase();
+    const forge = host === "github.com" ? "github" : host === "gitlab.com" ? "gitlab" : undefined;
+    if (!forge)
+        return undefined;
+    const segments = url.pathname.split("/").filter(Boolean);
+    if (segments.length < 2)
+        return undefined;
+    const pagesHost = `${segments[0]}.${forge}.io`.toLowerCase();
+    const project = segments.slice(1).join("/");
+    return project.toLowerCase() === pagesHost
+        ? `https://${pagesHost}`
+        : `https://${pagesHost}/${project}`;
+}
 /**
  * The `index/<host>/<namespace>/` this repo's entries land under: its path
  * minus the repo itself — one segment on GitHub, possibly nested on GitLab.
@@ -156,6 +239,7 @@ async function resolveAnswers(dir, flags) {
         ["--registry", flags.registry, badName],
         ["--base-url", flags.baseUrl, badUrl],
         ["--repo-url", flags.repoUrl, badUrl],
+        ["--logo", flags.logo, badLogo],
     ]) {
         if (value !== undefined) {
             const reason = check(value);
@@ -163,10 +247,30 @@ async function resolveAnswers(dir, flags) {
                 throw new CliError(`${flag} ${JSON.stringify(value)}: ${reason}`, EXIT.data);
         }
     }
+    // The git remote is the one thing a cloned-then-scaffolded repo already
+    // knows about itself, and everything else falls out of it: which forge runs
+    // the CI, where Pages will serve the site, and what `--announce` targets. A
+    // `--repo-url` overrides it, for scaffolding before the remote exists.
+    const remoteUrl = flags.repoUrl ? normalizeRepoUrl(flags.repoUrl) : gitRemoteUrl(dir);
+    const derivedBaseUrl = remoteUrl ? pagesUrlFromRepo(remoteUrl) : undefined;
+    const derivedForge = remoteUrl ? forgeFromRepoUrl(remoteUrl) : undefined;
     if (flags.quick) {
         const name = flags.name ?? defaultName;
-        const baseUrl = flags.baseUrl ?? "http://localhost:4321";
-        const withSkills = flags.withSkills ?? false;
+        // Falls back to localhost rather than a guess: `--quick` is the
+        // non-interactive path, and a wrong absolute URL is worse than an obvious
+        // placeholder the next step tells you to replace.
+        const baseUrl = flags.baseUrl ?? derivedBaseUrl ?? "http://localhost:4321";
+        // `--quick` asks nothing, so every one of these decisions is otherwise
+        // invisible — including the two that quietly did not happen: a self-hosted
+        // forge has no predictable Pages URL, and an unrecognised host falls back
+        // to GitHub Actions rather than guessing.
+        reportDerivation({
+            remoteUrl,
+            fromRemote: flags.repoUrl === undefined && remoteUrl !== undefined,
+            baseUrl: flags.baseUrl === undefined ? derivedBaseUrl : undefined,
+            forge: flags.forge === undefined ? derivedForge : undefined,
+            forgeFallback: flags.forge === undefined && derivedForge === undefined,
+        });
         return {
             name,
             title: flags.title ?? titleCase(name),
@@ -174,15 +278,15 @@ async function resolveAnswers(dir, flags) {
             registryAlias: flags.registry ?? name,
             registryHost: flags.registryHost ?? "ghcr.io",
             logo: flags.logo ?? "",
-            forge: flags.forge ?? "github",
+            forge: flags.forge ?? derivedForge ?? "github",
             git: flags.git ?? true,
-            withSkills,
-            // Only the combined layout writes an announce target, so only it pays
-            // for the derivation. An empty answer stays empty — a guessed index
-            // repo is worse than a placeholder that refuses to publish.
-            repoUrl: withSkills
-                ? (flags.repoUrl ?? gitRemoteUrl(dir) ?? repoUrlFromPages(baseUrl) ?? "")
-                : "",
+            install: flags.install ?? true,
+            withSkills: flags.withSkills ?? false,
+            // The combined layout needs an announce target, and every layout wants
+            // the header's repository link, which has no default to fall back on.
+            // Empty stays empty — nothing is guessed, and a `publish.toml` with no
+            // target refuses to publish.
+            repoUrl: remoteUrl ?? repoUrlFromPages(baseUrl) ?? "",
         };
     }
     prompts.intro("grim-indexer — new package index");
@@ -199,26 +303,36 @@ async function resolveAnswers(dir, flags) {
             placeholder: titleCase(name),
             defaultValue: titleCase(name),
         })));
+    if (remoteUrl) {
+        prompts.log.step(`Read from ${flags.repoUrl ? "--repo-url" : "the `origin` remote"}: ${remoteUrl}`);
+    }
+    // Asked before the base URL, because it is what the base URL defaults from.
+    // A repo cloned from its forge answers this without the user typing.
+    const repoUrl = remoteUrl ??
+        (await ask(prompts.text({
+            message: "Repository URL this index lives in",
+            placeholder: "https://github.com/you/your-index",
+            defaultValue: "",
+            // Blank is allowed: it writes a placeholder that refuses to publish,
+            // which beats forcing a URL the user does not have yet.
+            validate: (value) => (value ? (badUrl(value) ?? undefined) : undefined),
+        })));
+    // The whole point of asking for the repository first: on github.com and
+    // gitlab.com the Pages URL follows from it, so the answer is usually Enter.
+    // It stays a prompt because a custom domain (a CNAME on GitHub Pages, a
+    // GitLab Pages domain) is a fact this command cannot observe. The message
+    // names where the default came from, so accepting it is a decision rather
+    // than a shrug.
+    const pagesUrl = repoUrl === remoteUrl ? derivedBaseUrl : pagesUrlFromRepo(repoUrl);
     const baseUrl = flags.baseUrl ??
         (await ask(prompts.text({
-            message: "Base URL the index is served from",
-            placeholder: "https://index.example.com",
-            validate: (value) => badUrl(value ?? "") ?? undefined,
+            message: pagesUrl
+                ? `Base URL the index is served from (Enter for ${pagesUrl}, or type a custom domain)`
+                : "Base URL the index is served from",
+            placeholder: pagesUrl ?? "https://index.example.com",
+            defaultValue: pagesUrl ?? "",
+            validate: (value) => badUrl(value || (pagesUrl ?? "")) ?? undefined,
         })));
-    // Asked only for the combined layout — the standalone one writes no
-    // `publish.toml` and so announces nothing.
-    const derivedRepoUrl = gitRemoteUrl(dir) ?? repoUrlFromPages(baseUrl);
-    const repoUrl = !flags.withSkills
-        ? ""
-        : (flags.repoUrl ??
-            (await ask(prompts.text({
-                message: "Repository URL this index lives in (`grim publish --announce` targets it)",
-                placeholder: derivedRepoUrl ?? "https://github.com/you/your-index",
-                defaultValue: derivedRepoUrl ?? "",
-                // Blank is allowed: it writes a placeholder that refuses to publish,
-                // which beats forcing a URL the user does not have yet.
-                validate: (value) => (value ? (badUrl(value) ?? undefined) : undefined),
-            }))));
     const registryAlias = flags.registry ??
         (await ask(prompts.text({
             message: "Registry alias packages are published under",
@@ -228,32 +342,62 @@ async function resolveAnswers(dir, flags) {
         })));
     const logo = flags.logo ??
         (await ask(prompts.text({
-            message: "Brand logo (path or URL, blank for none)",
+            message: "Brand logo (site-root path like /logo.svg, or a URL; blank for none)",
             defaultValue: "",
+            validate: (value) => badLogo(value ?? "") ?? undefined,
         })));
+    // Prompted, not assumed. This is the committed allowlist the contribution
+    // gate bounds every entry's `ref` by, and defaulting it silently left every
+    // index refusing anything not on ghcr.io - including its own packages.
+    const registryHost = flags.registryHost ??
+        (await ask(prompts.text({
+            message: "OCI registry host packages are pulled from (the gate's allowlist)",
+            placeholder: "ghcr.io",
+            defaultValue: "ghcr.io",
+        })));
+    // Derived from the repository's host when that is recognisable, so the
+    // common case never sees this question. One repository runs on one forge —
+    // rendering both left every index carrying a pipeline it would never run.
+    const detectedForge = repoUrl === remoteUrl ? derivedForge : forgeFromRepoUrl(repoUrl);
+    if (detectedForge)
+        prompts.log.step(`CI: ${detectedForge}, from the repository host`);
     const forge = flags.forge ??
+        detectedForge ??
         (await ask(prompts.select({
             message: "CI to scaffold",
             options: [
                 { value: "github", label: "GitHub Actions" },
                 { value: "gitlab", label: "GitLab CI" },
-                { value: "both", label: "Both" },
             ],
             initialValue: "github",
         })));
     const git = flags.git ??
         (await ask(prompts.confirm({ message: "Initialize a git repository?", initialValue: true })));
+    // The lock is what pins the renderer this index builds and validates with,
+    // and CI runs `npm ci` against it — so an index without one is an index
+    // whose first push fails. Declining is still allowed; the next steps say
+    // what to run.
+    const install = flags.install ??
+        (await ask(prompts.confirm({
+            message: "Install dependencies now? (writes package-lock.json)",
+            initialValue: true,
+        })));
     return {
         name,
         title,
         baseUrl,
         registryAlias,
-        registryHost: flags.registryHost ?? "ghcr.io",
+        registryHost,
         logo,
         forge,
         git,
+        install,
         withSkills: flags.withSkills ?? false,
-        repoUrl,
+        // The Pages-URL fallback the `--quick` path has: someone who answered the
+        // base URL but left the repository blank has still said where this index
+        // lives, and dropping that left `repoUrl` empty — no header link, and a
+        // `publish.toml` that refuses to announce.
+        repoUrl: repoUrl || (repoUrlFromPages(baseUrl) ?? ""),
     };
 }
 /** Unwrap a clack prompt, turning Ctrl-C into a clean non-error abort. */
@@ -278,8 +422,22 @@ function siteConfig(answers) {
         site: answers.baseUrl,
         brand: answers.title,
         description: `${answers.title}, a Grimoire package index.`,
-        ...(answers.logo ? { favicon: answers.logo } : {}),
+        // `logo`, not `favicon`. They are deliberately different keys (see
+        // `SiteConfig`): a favicon is drawn to read at 16px, a logo goes in the
+        // header and becomes the default `og:image`. The prompt asks for a brand
+        // logo, so that is where the answer belongs.
+        ...(answers.logo ? { logo: answers.logo } : {}),
+        // The header's "github" link. Written whenever it could be derived —
+        // it has no default, because the only sane one would be somebody
+        // else's repository.
+        ...(answers.repoUrl ? { repoUrl: answers.repoUrl } : {}),
         registry: { alias: answers.registryAlias, index: answers.baseUrl },
+        // What the committed CI is rendered from. The remaining knobs
+        // (`nodeVersion`, `enrich`, `grimVersion`, `allowManualEdits`) are left
+        // to their defaults rather than written out — `grim-indexer ci` resolves
+        // them the same way, so an absent key and its default render identically.
+        // Which renderer runs is not here at all: that is `package-lock.json`.
+        ci: { forge: answers.forge },
     });
 }
 /**
@@ -298,8 +456,19 @@ function indexPolicy(answers) {
         trustedBots: [],
     });
 }
-/** The complete scaffold as (destination path, content) pairs — nothing touches disk yet. */
-function plan(answers, version) {
+/**
+ * The complete scaffold as (destination path, content) pairs — nothing
+ * touches disk yet.
+ *
+ * `ci` is the `ci` block that will be on disk when this returns, which is not
+ * always the one derived from the answers: `write` leaves an existing
+ * `index.config.json` alone unless `--force`. Rendering the workflows from
+ * the answers while the config kept its own values produced a tree whose
+ * committed CI did not match its committed config — and `ci --check`, which
+ * reads only the config, then failed on a tree `init` had just reported as
+ * successful.
+ */
+function plan(answers, version, ci) {
     const vars = {
         name: answers.name,
         title: answers.title,
@@ -310,27 +479,26 @@ function plan(answers, version) {
         announceRepo: answers.repoUrl || UNDERIVED,
         announceNamespace: (answers.repoUrl && announceNamespace(answers.repoUrl)) || UNDERIVED,
         version,
-        // The reusable workflows are pinned by tag; Renovate's `github-actions`
-        // manager bumps this in every scaffolded repo.
-        ref: `v${version}`,
+        // `title` is free text and lands inside a JSON string literal in
+        // package.json. A quote in it would close that string and produce a
+        // manifest npm refuses to read. Every other template puts it in prose.
+        titleJson: JSON.stringify(answers.title).slice(1, -1),
     };
-    const from = (rel, dest) => ({
-        path: dest,
-        content: render(readTemplate(rel), vars, rel),
-    });
+    const from = (rel, dest) => ({ path: dest, content: fromTemplate(rel, vars) });
     const files = [
         { path: "index/.gitkeep", content: "" },
         { path: "index.config.json", content: siteConfig(answers) },
         { path: "index-policy.json", content: indexPolicy(answers) },
         from("gitignore", ".gitignore"),
+        from("gitattributes", ".gitattributes"),
+        from("package.json", "package.json"),
         from("README.md", "README.md"),
     ];
-    if (answers.forge === "github" || answers.forge === "both") {
-        files.push(from("github-pages.yml", ".github/workflows/pages.yml"));
-        files.push(from("github-validate.yml", ".github/workflows/validate.yml"));
-    }
-    if (answers.forge === "gitlab" || answers.forge === "both") {
-        files.push(from("gitlab-ci.yml", ".gitlab-ci.yml"));
+    // The same renderer `grim-indexer ci` uses, driven by the `ci` block that
+    // will be on disk — so the scaffold is drift-free by construction and the
+    // guard it emits passes on the first push.
+    for (const [dest, content] of renderCi(resolveCi(ci))) {
+        files.push({ path: dest, content });
     }
     if (answers.withSkills) {
         files.push({ path: "skills/.gitkeep", content: "" });
@@ -380,6 +548,32 @@ function initGit(dir) {
         return false;
     }
 }
+/**
+ * Generate `package-lock.json` by installing. The lock is the load-bearing
+ * part: CI runs `npm ci` against it, so a repository without one cannot build,
+ * and which renderer runs would otherwise be resolved fresh on every runner.
+ *
+ * A failure is reported and survived — the scaffold is complete either way,
+ * and the next steps say what to run.
+ */
+function npmInstall(dir) {
+    try {
+        // `shell` on Windows: npm ships as `npm.cmd`, libuv's non-shell PATH
+        // search only tries `.com`/`.exe`, and Node refuses to spawn a `.cmd`
+        // without it — so without this branch the install could never succeed
+        // there, and every Windows scaffold silently shipped without a lockfile.
+        execFileSync("npm", ["install"], {
+            cwd: dir,
+            stdio: "ignore",
+            shell: process.platform === "win32",
+        });
+        return true;
+    }
+    catch {
+        console.error("warning: `npm install` failed - run it yourself to write package-lock.json");
+        return false;
+    }
+}
 function nextSteps(result, answers) {
     const rel = path.relative(process.cwd(), result.dir);
     // A relative path that climbs out of the working directory is worse than
@@ -387,18 +581,26 @@ function nextSteps(result, answers) {
     const target = rel === "" ? "" : rel.startsWith("..") ? result.dir : rel;
     const cd = target === "" ? "" : `cd ${target}\n`;
     const steps = [
-        "Add packages under index/<namespace>/<package>/metadata.json",
+        // The forge-host segment is mandatory: the gate refuses anything outside
+        // `index/<host>/<namespace>/<package>/metadata.json`, and a shallow first
+        // commit builds locally without complaint before failing every review.
+        "Add packages under index/<host>/<namespace>/<package>/metadata.json",
+        "Commit package-lock.json - CI installs from it, so it is not optional",
         "Push to your forge — CI builds and publishes the site",
     ];
     if (answers.baseUrl === "http://localhost:4321") {
-        steps.push("Set baseUrl in index.config.json to the real site URL");
+        // Both keys, because the placeholder lands in both: `site` drives the
+        // deployment URL, `registry.index` is the address this index hands its
+        // visitors to add it with. Naming only the first left the copy-paste
+        // block on the published site pointing at localhost.
+        steps.push("Set site and registry.index in index.config.json to the real site URL");
     }
     if (answers.withSkills && !answers.repoUrl) {
         steps.push(`Set [announce] repository + namespace in publish.toml — both are ${UNDERIVED}, ` +
             "and `grim publish --announce` refuses to run until they name this repo");
     }
     return [
-        `${cd}npx @grimoire-rs/indexer build`,
+        `${cd}${result.installed ? "" : "npm install\n"}npm run dev      # preview it locally`,
         "",
         "Then:",
         ...steps.map((step, i) => `  ${i + 1}. ${step}`),
@@ -408,9 +610,19 @@ export async function init(dir, flags, version) {
     const target = path.resolve(dir);
     const answers = await resolveAnswers(target, flags);
     fs.mkdirSync(target, { recursive: true });
-    const files = write(target, plan(answers, version), flags.force ?? false);
+    // Which `ci` block the workflows are rendered from depends on which one
+    // survives `write`: an existing `index.config.json` is kept unless
+    // `--force`, and its settings — not the answers — are what the committed
+    // CI has to match. A malformed one is a data error either way, and
+    // `loadCiConfig` raises it rather than papering over it with defaults.
+    const keepsExistingConfig = fs.existsSync(path.join(target, CONFIG_FILE)) && !(flags.force ?? false);
+    const ci = keepsExistingConfig
+        ? await loadCiConfig(target)
+        : { forge: answers.forge };
+    const files = write(target, plan(answers, version, ci), flags.force ?? false);
     const gitInitialized = answers.git ? initGit(target) : false;
-    const result = { dir: target, files, gitInitialized };
+    const installed = answers.install ? npmInstall(target) : false;
+    const result = { dir: target, files, gitInitialized, installed };
     for (const file of files) {
         console.log(`  ${file.outcome.padEnd(12)}${file.path}`);
     }
@@ -419,6 +631,18 @@ export async function init(dir, flags, version) {
         console.error(`\n${skipped.length} file(s) differ from the scaffold and were left alone. ` +
             `Re-run with --force to overwrite them.`);
     }
+    // Same contract `grim-indexer ci` has: generated CI this config no longer
+    // renders is reported, never deleted. Silence here left an orphaned
+    // pipeline behind — and the drift guard failing on the next push with no
+    // hint of where it came from.
+    const orphaned = await staleCi(target, renderCi(resolveCi(ci)));
+    for (const relative of orphaned) {
+        console.log(`  ${"stale".padEnd(12)}${relative}`);
+    }
+    if (orphaned.length > 0) {
+        console.error(`\n${orphaned.length} generated file(s) are no longer rendered by ${CONFIG_FILE} — ` +
+            `delete them, or \`npm run ci:check\` keeps failing`);
+    }
     prompts.note(nextSteps(result, answers), "Next steps");
     prompts.outro(`Index "${answers.name}" ready in ${target}`);
     return EXIT.ok;