create-bascik 1.0.0-rc.1 → 1.0.0-rc.11

package/README.md

@@ -3,35 +3,40 @@
 [![Unit lines](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbascikdev%2Fbascik%2Fmain%2Fcreate%2Ftest-coverage.json&query=%24.total.lines.pct&label=unit%20lines&suffix=%25&color=brightgreen)](https://github.com/bascikdev/bascik/blob/main/create/test-coverage.json)
 [![Unit functions](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Fbascikdev%2Fbascik%2Fmain%2Fcreate%2Ftest-coverage.json&query=%24.total.functions.pct&label=unit%20functions&suffix=%25&color=brightgreen)](https://github.com/bascikdev/bascik/blob/main/create/test-coverage.json)
 
-Interactive project initializer for [Bascik](https://bascik.dev).
+Interactive project initializer for [Bascik](https://bascik.dev): the command behind `npm create bascik`. Use it to start a new Bascik site with a working starter, editor settings, tests, and the agent skills. Requires Node.js 22.22 or newer. The [Getting Started guide](https://bascik.dev/getting-started) walks through the result, and [Create App internals](https://bascik.dev/internals/create-app) explains how the scaffolder works.
 
 ## Quick Start
 
 Scaffold a new Bascik project in one command:
 
 ```sh
-npm create bascik@latest my-site -y
+npm create bascik@rc my-site -y
 ```
 
 Pass a project name as an argument or run without arguments to be prompted:
 
 ```sh
-npm create bascik@latest
+npm create bascik@rc
 ```
 
+The name is a new folder under the current one, such as `my-site` or `sites/my-site`; `.`, `..`, absolute paths and spaces are refused. A folder that already has one of the starter's files, such as `package.json` or `src/pages/index.html`, is refused before anything is written. To add Bascik to an existing project, see [Manual Setup](https://bascik.dev/getting-started#manual-setup).
+
 ## What it scaffolds
 
 `create-bascik` creates a complete, ready-to-run starter site:
 
 ```text
 my-site/
-├── .github/skills/bascik/SKILL.md  ← AI Copilot skill file
-├── .claude/skills/bascik/SKILL.md  ← Claude skill file
+├── AGENTS.md                       ← Project brief for coding assistants
+├── CLAUDE.md                       ← Imports AGENTS.md for Claude Code
+├── .agents/skills/                 ← Bascik agent skills for Copilot, Cursor, Codex, and others (on Y)
+├── .claude/skills/                 ← The same skills for Claude Code (on Y)
 ├── .vscode/
 │   ├── launch.json                 ← Debug launchers for dev server and tests
-│   └── extensions.json             ← Recommends official Bascik extension
+│   ├── extensions.json             ← Recommends official Bascik extension
+│   └── settings.json               ← Stops false VS Code errors on pages with several scripts
 ├── src/
-│   ├── components/                 ← site-meta, site-header, site-footer, feat-card, my-counter
+│   ├── components/                 ← site-meta, site-header, site-footer, feature-card, my-counter, contact-form
 │   └── pages/                      ← index.html, about.html, contact.html, 404.html, css/styles.css
 ├── package.json                    ← dev, build, lint, test, and e2e scripts
 └── .gitignore
@@ -39,6 +44,23 @@ my-site/
 
 The starter does not include `bascik.config.ts` because it uses Bascik's built-in defaults. Add a config only when the project needs non-default behavior.
 
+## Agent skills
+
+After scaffolding, `create-bascik` asks:
+
+```text
+Install the Bascik agent skills for coding assistants (Claude Code, Copilot, Cursor, Codex...)? (Y/n)
+```
+
+Yes, the default and what `-y` answers, runs the [skills CLI](https://skills.sh) to install every [Bascik skill](https://bascik.dev/agent-skills) except the opt-in `bascik-refactor`, at the release tag matching the Bascik version scaffolded. `--no-skills` skips it. When you skip it, or the install fails, for example offline, the project is still created and the command to run later is printed, pinned to the same release tag.
+
+| Flag           | Effect                                             |
+| :------------- | :------------------------------------------------- |
+| `-y`, `--yes`  | Answer every question with its default             |
+| `--no-skills`  | Do not install the agent skills                    |
+| `--no-install` | Do not run `npm install`, nor start the dev server |
+| `--no-dev`     | Do not start the dev server                        |
+
 After scaffolding:
 
 ```sh
@@ -46,7 +68,59 @@ cd my-site
 npm run dev
 ```
 
-Your site will be live at `http://localhost:8080`.
+Your site will be live at `http://localhost:8080` for the default template, `http://127.0.0.1:8787` for Cloudflare, or `http://127.0.0.1:8888` for Netlify.
+
+## Templates
+
+Pick a starter with `--template <name>` (or `--template=<name>`). Without the flag, the interactive prompts ask whether the site deploys to Cloudflare Workers, then to Netlify; with `-y` and no flag, you get the default.
+
+| Template     | What you get                                                                                                             |
+| :----------- | :----------------------------------------------------------------------------------------------------------------------- |
+| `default`    | The static starter above. `static` is accepted as an alias.                                                              |
+| `cloudflare` | The same starter plus the [Cloudflare adapter](https://bascik.dev/deployment/cloudflare), Wrangler, and an edge demo.    |
+| `netlify`    | The same starter plus the [Netlify adapter](https://bascik.dev/deployment/netlify), a `netlify.toml`, and the edge demo. |
+
+```sh
+npm create bascik@rc my-site -- --template cloudflare
+```
+
+The `--` matters: npm keeps flags placed before it for itself and does not pass them on, so `--template` has to follow a `--`. `-y` is the exception, since `create-bascik` also reads npm's own `yes` setting (`npm create bascik@rc my-site -y -- --template cloudflare` skips every prompt).
+
+The Cloudflare template differs from the default in these files only:
+
+- `package.json`: `@bascik/adapter-cloudflare` and `wrangler` as dev dependencies; `dev` runs `bascik --target cloudflare` with source watching and browser live reload in the real local platform runtime; `build` runs `bascik --build --target cloudflare`; `preview` and `deploy` run Wrangler from the emitted `dist/.bascik/cloudflare/` folder.
+- `src/pages/edge.html`: a page with a `data-bascik-server` script that the Worker renders on every request, linked from a fourth feature card on the home page.
+- `src/api/hello.ts`: an API route served at `/api/hello`.
+- `e2e/app.spec.ts`: one extra test covering the edge page.
+- `.gitignore`: ignores `.wrangler/`.
+
+After scaffolding a Cloudflare project:
+
+```sh
+npm run dev       # watched workerd development on http://127.0.0.1:8787
+npm run build     # bascik --build --target cloudflare
+npm run preview   # run the bundle locally in workerd
+npm run deploy    # wrangler deploy
+```
+
+The Netlify template differs from the default in these files only:
+
+- `package.json`: `@bascik/adapter-netlify` and `netlify-cli` as dev dependencies; `dev` runs `bascik --target netlify` with source watching and browser live reload through the locally installed Netlify Dev; `build` runs `bascik --build --target netlify && bascik-netlify-install`; `preview` and `deploy` run the Netlify CLI through `npx`.
+- `netlify.toml`: builds with `npm run build`, publishes `publish/`, and uses Netlify's `URL` as the site URL unless `BASCIK_SITE_URL` is set.
+- `src/pages/edge.html` and `src/api/hello.ts`: the edge demo and API route, run in the Netlify Function.
+- `e2e/app.spec.ts`: one extra test covering the edge page.
+- `.gitignore`: ignores `publish/` and `.netlify/`.
+
+After scaffolding a Netlify project:
+
+```sh
+npm run dev       # watched Netlify development on http://127.0.0.1:8888
+npm run build     # bascik --build --target netlify && bascik-netlify-install
+npm run preview   # netlify dev --dir publish
+npm run deploy    # netlify deploy --build --prod
+```
+
+Both adapter development workflows use a local HTTP-only proxy; `--port` and `--host` override its public address. A rebuild or failed build may return 503, but the watcher stays alive and retries after the next source edit. Live reload is injected only by that proxy, never into production artifacts. `preview` remains a production-output workflow without Bascik's source watcher, and bare `bascik` remains the Node development server.
 
 ## Development & Testing
 
@@ -58,3 +132,5 @@ yarn create:typecheck  # TypeScript type check
 yarn create:unit       # run unit tests
 yarn create:coverage   # run unit tests with coverage report
 ```
+
+The integration tests compile scaffolded projects with the built framework and Cloudflare adapter, so run `yarn pkg:build && yarn adapter:cf:build` first (CI does the same).

package/dist/agent-setup.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @module agent-setup
+ *
+ * Sets a new Bascik project up for coding assistants:
+ *
+ *  - `AGENTS.md` is a short project brief that GitHub Copilot, Cursor, Codex,
+ *    Gemini CLI and others read: the commands, the house rules, and where the
+ *    agent skills live.
+ *  - `CLAUDE.md` imports that brief with `@AGENTS.md`. Claude Code reads
+ *    CLAUDE.md, and skips AGENTS.md when a CLAUDE.md exists, so the import is
+ *    what makes every assistant read the same brief.
+ *  - The Bascik agent skills are installed with the skills CLI
+ *    (https://skills.sh) into `.agents/skills/` and `.claude/skills/`, pinned
+ *    to the Bascik version being set up. The opt-in `bascik-refactor` skill is
+ *    left out.
+ *
+ * Existing AGENTS.md and CLAUDE.md files are merged, never replaced. A skills
+ * install that fails, such as when offline, never fails the setup: the report
+ * says which command to run later.
+ *
+ * Two identical copies exist, `create/src/agent-setup.ts` for
+ * `npm create bascik` and `pkg/src/lib/agent-setup.ts` for `bascik init`.
+ * `create/src/agent-setup.test.ts` fails when they differ.
+ */
+import { type SpawnSyncOptions, type SpawnSyncReturns } from "node:child_process";
+/** The GitHub repository the skills CLI installs the Bascik skills from. */
+export declare const SKILLS_REPO = "bascikdev/bascik";
+/**
+ * The skills CLI, pinned so its flags cannot change under a released
+ * create-bascik. 1.7.4 needs Node 22.20, below Bascik's 22.22 floor.
+ */
+export declare const SKILLS_CLI = "skills@1.7.4";
+/** The skills CLI agents whose folders a project gets, in SKILL_DESTINATIONS order. */
+export declare const SKILL_AGENTS: readonly ["universal", "claude-code"];
+/**
+ * Project directories that receive the agent skills. `.agents/skills` is the shared location read by GitHub
+ * Copilot, Cursor, Codex, Gemini CLI, OpenCode, and others; Claude Code reads `.claude/skills`.
+ */
+export declare const SKILL_DESTINATIONS: readonly [".agents/skills", ".claude/skills"];
+/**
+ * The skills a new project gets. The skills CLI has no way to leave one out
+ * and silently ignores a name it does not know, so this is the full list of
+ * the repository's `skills/` folders minus OPT_IN_SKILLS, and a test keeps it
+ * that way.
+ */
+export declare const PROJECT_SKILLS: readonly ["bascik", "bascik-compatibility", "bascik-components", "bascik-config", "bascik-migrate", "bascik-scripts", "bascik-seo", "bascik-testing"];
+/** Skills readers install on purpose with `--skill <name>`. */
+export declare const OPT_IN_SKILLS: readonly ["bascik-refactor"];
+export declare const SKILLS_QUESTION = "Install the Bascik agent skills for coding assistants (Claude Code, Copilot, Cursor, Codex...)? (Y/n) ";
+/**
+ * Replaces the GitHub source, such as with a local checkout of the
+ * repository, so tests install without the network. Used as given: no
+ * version pin and no fallback.
+ */
+export declare const SKILLS_SOURCE_ENV = "BASCIK_SKILLS_SOURCE";
+/** The git tag the skills for `version` are released under, or undefined when it is not a release version. */
+export declare function skillsRef(version: string | undefined): string | undefined;
+/** The arguments after `npx skills` that install the project skills from `source`. */
+export declare function skillsAddArgs(source: string): string[];
+/** The command a reader runs to install the project skills, at `ref` when given. */
+export declare function skillsCommand(ref?: string): string;
+type SpawnSyncFunction = (command: string, args: string[], options: SpawnSyncOptions) => SpawnSyncReturns<Buffer | string>;
+/**
+ * The command that runs `npx <args>`. On Windows `npx` is `npx.cmd`, which
+ * Node cannot start directly, so it goes through `cmd.exe` the way
+ * create-bascik's `npmInvocation` runs npm.
+ */
+export declare function npxInvocation(args: string[], platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): {
+    command: string;
+    args: string[];
+};
+/**
+ * The lines that give the command to run later: pinned to `ref` when there
+ * is one, so the skills match the Bascik version, and how to drop the pin if
+ * that tag does not exist yet.
+ */
+export declare function skillsLaterLines(ref: string | undefined): string[];
+export interface SkillsInstallResult {
+    /**
+     * `pinned`: installed at the release tag. `latest`: the tag install failed
+     * and the default branch worked. `custom`: installed from SKILLS_SOURCE_ENV.
+     * `failed`: nothing was installed.
+     */
+    status: "pinned" | "latest" | "custom" | "failed";
+    /** The release tag that was tried, when the version had one. */
+    ref?: string;
+    /** Why the last attempt failed. */
+    error?: string;
+    /** The command to run later, when status is `failed`, pinned to `ref` when there is one. */
+    command: string;
+}
+/**
+ * Install the project skills into `cwd` with the skills CLI: at the release
+ * tag for `version` first, then from the default branch. Output is captured
+ * so a failed first attempt does not alarm anyone. Never throws.
+ */
+export declare function installSkills(cwd: string, options?: {
+    version?: string;
+    platform?: NodeJS.Platform;
+    env?: NodeJS.ProcessEnv;
+    spawn?: SpawnSyncFunction;
+}): SkillsInstallResult;
+/** What to tell the user about a skills install, one line per entry. */
+export declare function skillsReportLines(result: SkillsInstallResult): string[];
+/** The heading of the Bascik section, which is how a merge finds it again. */
+export declare const AGENTS_SECTION_HEADING = "## Bascik";
+/** The line in CLAUDE.md that imports the brief. Claude Code skips it inside code. */
+export declare const CLAUDE_IMPORT = "@AGENTS.md";
+export interface AgentsOptions {
+    template?: "default" | "cloudflare" | "netlify";
+    /**
+     * The commands that run the Bascik dev server and build, when the
+     * project's `dev` and `build` npm scripts do not, such as `bascik init` in
+     * a project whose scripts run another tool. Default: `npm run dev` and
+     * `npm run build`.
+     */
+    commands?: {
+        dev?: string;
+        build?: string;
+    };
+}
+/** The Bascik section of AGENTS.md, added on its own to an AGENTS.md that has none. */
+export declare function agentsSection(options?: AgentsOptions): string;
+/** A new project's AGENTS.md. */
+export declare function agentsMd(options?: AgentsOptions): string;
+/** A new project's CLAUDE.md: the import line, then room for notes only Claude Code needs. */
+export declare const CLAUDE_MD = "@AGENTS.md\n\n<!-- Claude Code reads this file instead of AGENTS.md, so the line above imports the shared brief. Add notes only Claude Code needs below. -->\n";
+export type AgentFileStatus = "created" | "updated" | "unchanged" | "failed";
+export interface AgentFilesReport {
+    agents: AgentFileStatus;
+    claude: AgentFileStatus;
+}
+/** Add the Bascik section to an AGENTS.md, keeping what is there. */
+export declare function mergeAgentsMd(existing: string | undefined, options?: AgentsOptions): {
+    status: "created" | "updated" | "unchanged";
+    text: string;
+};
+/** Add the `@AGENTS.md` import to a CLAUDE.md, keeping what is there. */
+export declare function mergeClaudeMd(existing: string | undefined): {
+    status: "created" | "updated" | "unchanged";
+    text: string;
+};
+/**
+ * Write or merge AGENTS.md and CLAUDE.md in `root`. Never throws; the report
+ * says what happened to each file.
+ */
+export declare function writeAgentFiles(root: string, options?: AgentsOptions): Promise<AgentFilesReport>;
+/** Lines worth showing the user: what was added to an existing file, and what to fix by hand. */
+export declare function agentFilesReportLines(report: AgentFilesReport): string[];
+/** Whether an answer to a "(Y/n)" question is no. Anything else, including Enter, is yes. */
+export declare function answeredNo(answer: string): boolean;
+export interface Prompter {
+    /** Print `question` and resolve with the next line, or "" once input has ended. */
+    ask(question: string): Promise<string>;
+    close(): void;
+}
+/**
+ * Ask questions on a terminal or a pipe. Lines that arrive before their
+ * question, as when answers are piped in, are kept for it, and once input
+ * ends (stdin closed, or `</dev/null`) every question gets "", its default,
+ * so a run without a terminal never hangs or dies mid-way.
+ */
+export declare function createPrompter(input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Prompter;
+export {};