create-trokky 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Trokky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# create-trokky
+
+Compose a [Trokky](https://trokky.dev) project: pick where it runs, where content lives, and how
+much of the stack you want.
+
+```bash
+npm create trokky@latest
+```
+
+Not on npm yet? It runs straight from the repo, no install:
+
+```bash
+npx github:Trokky/generator my-site
+```
+
+```
+Where will it run?
+  1) Cloudflare Workers — No server, no disk. D1 + R2.
+  2) Node / Express     — A server you run: VPS, Docker, Railway.
+
+What do you want?
+  1) API only              — Headless. Bring your own frontend.
+  2) API + Studio          — The admin UI, for editors.
+  3) API + Studio + a site — An Astro frontend as well.
+```
+
+Non-interactive, for scripts and CI:
+
+```bash
+npm create trokky@latest my-site -- --yes --target=workers --parts=full-site --content=magazine
+```
+
+## What it will not let you build
+
+The generator refuses impossible combinations and says why, instead of handing you a project that
+compiles and dies on startup:
+
+```
+$ npm create trokky@latest x -- --yes --target=workers --images=sharp
+That combination cannot be built:
+  images: "sharp" is not available here.
+    sharp is a native libvips binding and Workers runs no native code.
+    Try: cloudflare-images, none
+```
+
+Every such rule lives in [`manifest.json`](./manifest.json) as data — axes, options, constraints,
+each with the reason it exists. **Nothing reimplements them.** `npm create trokky@latest`, the
+trokky.build configurator and `trokky new` in the Go CLI all read that one file, so they cannot
+drift apart.
+
+## The same site, either runtime
+
+`--parts=full-site` gives you an Astro frontend on **both** targets, and the pages are
+byte-identical between them:
+
+| | Workers | Node |
+|---|---|---|
+| Astro adapter | `@astrojs/cloudflare` | `@astrojs/node` in middleware mode, mounted on Express |
+| How a page reaches Trokky | bindings from `cloudflare:workers` | the core, passed in as `Astro.locals` |
+| Sample content appears | after the claim, in `waitUntil` | at boot, when the store is empty |
+| Thumbnails | Cloudflare Images at upload | sharp at upload |
+
+Only `src/trokky/page.ts` and `astro.config.mjs` differ. Every page, every layout and the query
+helper are the same file — and on both runtimes a page reads content **in-process**, with no API
+token and no HTTP round trip.
+
+## Adding a content model
+
+A content model is two directories and a manifest entry. Nothing in the generator learns its
+name.
+
+1. `files/content/<id>/` — `src/trokky/schemas.ts`, `structure.ts`, `seed.ts`, and any
+   `public/seed/` assets the seed uploads.
+2. `files/site/<id>/` — the Astro pages, layouts and `src/trokky/site.ts` that render it.
+   **Optional**: leave it out and the model is headless-only, and the configurator will not offer
+   it a frontend. Pages are written against particular collections, which is why a site belongs
+   to its model rather than being shared.
+3. `manifest.json` — add the option under the `content` axis. If it has a site, add its id to the
+   `content-needs-schemas` constraint's `allow` list.
+
+`test/extensibility.test.ts` holds that contract: it fails if a model has pages the configurator
+will not offer, or is offered a frontend it has no pages for.
+
+## Using it as a library
+
+```ts
+import { generate, validate, optionsFor, withDefaults } from 'create-trokky'
+
+optionsFor('data', { target: 'workers' })   // ['cloudflare-d1']
+validate({ target: 'workers', images: 'sharp' })   // { valid: false, problems: [...] }
+
+const files = generate(withDefaults({ name: 'my-site', target: 'workers' }))
+// Map<path, string | Uint8Array> — pure, nothing touches the disk
+```
+
+`generate` is pure, and it takes its template files from a source you hand it — so the same
+function serves a terminal, a browser and an API install:
+
+```ts
+import { generate, inlineFileSource } from 'create-trokky'
+import { text } from 'create-trokky/generated/files-text'
+
+// No filesystem: this runs in a browser or a Worker.
+const files = generate(config, inlineFileSource({ text, binary: {} }))
+```
+
+`create-trokky/node` adds `fsFileSource()` and `writeTree()`, which the CLI uses. Nothing in the
+main export touches `node:fs`, so a browser bundle never pulls it in.
+
+## Releasing
+
+Tag a version and the workflow publishes it, authenticating through npm **trusted publishing**:
+GitHub Actions mints a short-lived OIDC token and npm exchanges it for publish rights, so no
+long-lived token lives in this repo. npm attaches a provenance attestation automatically.
+
+Requires npm CLI 11.5.1 or later, which is why the workflow upgrades npm before publishing —
+Node 22 ships npm 10, and without the upgrade npm quietly falls back to looking for a token. Before it does, it installs the packed tarball into
+an empty project and generates from *that* — because `files/` is most of this package, and npm's
+own ignore rules can quietly drop parts of it. Both failures that shipped this way looked perfect
+in the source tree: `.gitignore` is never packaged, and an empty directory survives neither git
+nor npm.
+
+## Development
+
+```bash
+npm install
+npm test          # the rules and the shape of generated trees
+npm run smoke     # generate → install → build → boot → claim, per composition
+```
+
+`npm test` proves a generated tree is coherent. **`npm run smoke` proves it runs**: it generates,
+installs, builds, boots, claims the instance the way a first visitor would, checks the claim
+cannot happen twice, and fetches a thumbnail — the far end of the whole media pipeline.
+
+It has earned every step of that. It caught a Node project that typechecked, generated cleanly and died
+on startup because nothing imported its adapters; two type errors in the emitted server; a
+frontend that could not build on Node because a shared file imported a Workers-only one; and a
+Node config with no image variants, where every page looked fine and every thumbnail was a 404.

package/dist/cli.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * `npm create trokky@latest` — compose a project and write it out.
+ *
+ * Every rule it applies comes from the manifest, so this file knows nothing about what can go
+ * with what. It asks, it validates, it writes.
+ */
+export {};

package/dist/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+/**
+ * `npm create trokky@latest` — compose a project and write it out.
+ *
+ * Every rule it applies comes from the manifest, so this file knows nothing about what can go
+ * with what. It asks, it validates, it writes.
+ */
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout, argv, exit } from 'node:process';
+import { randomBytes } from 'node:crypto';
+import { resolve } from 'node:path';
+import { manifest, secretsFor } from './manifest.js';
+import { withDefaults } from './config.js';
+import { validate, optionsFor, describe } from './validate.js';
+import { generate } from './generate.js';
+import { fsFileSource } from './files-node.js';
+import { writeTree } from './write.js';
+function parseFlags(args) {
+    const flags = {};
+    for (const arg of args) {
+        const match = /^--([a-z-]+)(?:=(.*))?$/.exec(arg);
+        if (match)
+            flags[match[1]] = match[2] ?? 'true';
+        else if (!arg.startsWith('-'))
+            flags.name ??= arg;
+    }
+    return flags;
+}
+async function main() {
+    const flags = parseFlags(argv.slice(2));
+    const interactive = flags.yes !== 'true' && stdin.isTTY;
+    const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
+    const ask = async (question, options, fallback) => {
+        if (!rl)
+            return fallback;
+        const axisOptions = manifest.axes.find(a => options.includes(a.options[0]?.id));
+        console.log(`\n${question}`);
+        options.forEach((id, i) => {
+            const option = manifest.axes.flatMap(a => a.options).find(o => o.id === id);
+            console.log(`  ${i + 1}) ${option?.title ?? id}${option?.hint ? ` — ${option.hint}` : ''}`);
+        });
+        void axisOptions;
+        const answer = (await rl.question(`> [${options.indexOf(fallback) + 1}] `)).trim();
+        if (!answer)
+            return fallback;
+        const index = Number(answer) - 1;
+        return options[index] ?? (options.includes(answer) ? answer : fallback);
+    };
+    const name = flags.name ?? (rl ? (await rl.question('\nProject name > [my-trokky-site] ')).trim() || 'my-trokky-site' : 'my-trokky-site');
+    const target = (flags.target ?? (await ask('Where will it run?', ['workers', 'node'], 'workers')));
+    const chosen = { target };
+    for (const axisId of ['parts', 'content', 'data', 'media', 'images']) {
+        const available = optionsFor(axisId, chosen);
+        const preset = flags[axisId];
+        if (preset) {
+            chosen[axisId] = preset;
+            continue;
+        }
+        const fallback = manifest.defaults[target]?.[axisId] ?? available[0];
+        // One option left is not a question; say what it is and move on.
+        chosen[axisId] = available.length <= 1
+            ? available[0] ?? fallback
+            : await ask(manifest.axes.find(a => a.id === axisId).title, available, available.includes(fallback) ? fallback : available[0]);
+    }
+    await rl?.close();
+    const config = withDefaults({ name, ...chosen });
+    const result = validate(config);
+    if (!result.valid) {
+        console.error(`\nThat combination cannot be built:\n${describe(result.problems)}`);
+        exit(1);
+    }
+    const target_dir = resolve(flags.out ?? name);
+    writeTree(generate(config, fsFileSource()), target_dir);
+    const secrets = secretsFor(config);
+    console.log(`\nCreated ${config.name} in ${target_dir}\n`);
+    console.log(`  ${config.parts === 'api' ? 'API' : config.parts === 'studio' ? 'API + Studio' : 'API + Studio + site'} · ${config.data} · ${config.media} · thumbnails: ${config.images}\n`);
+    console.log('Next:');
+    console.log(`  cd ${config.name}`);
+    console.log(`  cp ${config.target === 'workers' ? '.dev.vars.example .dev.vars' : '.env.example .env'}`);
+    for (const secret of secrets) {
+        // Only the generated ones get a value here; an endpoint or a bucket name is yours to fill in.
+        if (secret.generate) {
+            console.log(`  # ${secret.name}=${randomBytes(secret.generate === 'hex32' ? 32 : 24).toString('hex')}`);
+        }
+        else {
+            console.log(`  # ${secret.name}=   (${secret.optional ? 'optional — ' : ''}${secret.why})`);
+        }
+    }
+    console.log('  npm install');
+    console.log(config.target === 'workers' ? '  npm run build && npm run preview' : '  npm run dev');
+}
+main().catch(error => {
+    console.error(error instanceof Error ? error.message : error);
+    exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,24 @@
+/**
+ * A composition, and the defaults that fill in what the caller did not say.
+ */
+export interface ProjectConfig {
+    /** Directory and package name; also the Worker name on Cloudflare. */
+    name: string;
+    target: 'workers' | 'node';
+    data: 'filesystem-data' | 'postgres-data' | 'cloudflare-d1';
+    media: 'filesystem-media' | 'cloudflare-r2' | 's3-media';
+    images: 'sharp' | 'cloudflare-images' | 'none';
+    parts: 'api' | 'studio' | 'full-site';
+    /** Open on purpose: a content model is a pair of directories, not a value this file knows. */
+    content: string;
+    /** Version range written into the generated package.json for @trokky/* . */
+    trokkyVersion: string;
+}
+export type PartialConfig = Partial<ProjectConfig> & {
+    name: string;
+    target: ProjectConfig['target'];
+};
+/** Fill a partial choice from the manifest's per-target defaults. */
+export declare function withDefaults(input: PartialConfig): ProjectConfig;
+export declare const hasStudio: (config: ProjectConfig) => boolean;
+export declare const hasFrontend: (config: ProjectConfig) => boolean;

package/dist/config.js

@@ -0,0 +1,29 @@
+/**
+ * A composition, and the defaults that fill in what the caller did not say.
+ */
+import { manifest } from './manifest.js';
+/** Fill a partial choice from the manifest's per-target defaults. */
+export function withDefaults(input) {
+    const defaults = manifest.defaults[input.target] ?? {};
+    const pick = (key) => {
+        const chosen = input[key];
+        if (typeof chosen === 'string')
+            return chosen;
+        const fallback = defaults[key];
+        if (!fallback)
+            throw new Error(`No default for "${key}" on target "${input.target}"`);
+        return fallback;
+    };
+    return {
+        name: input.name,
+        target: input.target,
+        data: pick('data'),
+        media: pick('media'),
+        images: pick('images'),
+        parts: pick('parts'),
+        content: pick('content'),
+        trokkyVersion: input.trokkyVersion ?? '^3.4.1',
+    };
+}
+export const hasStudio = (config) => config.parts !== 'api';
+export const hasFrontend = (config) => config.parts === 'full-site';

package/dist/emit.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The files a composition produces that are not simply copied: anything whose *contents* depend
+ * on the choices. Copied files live under `files/`; computed ones are built here.
+ */
+import type { ProjectConfig } from './config.js';
+export declare function packageJson(config: ProjectConfig): string;
+/** Astro renders on request on both targets; only the adapter differs. */
+export declare function astroConfig(config: ProjectConfig): string;
+/**
+ * How a page gets hold of Trokky. The one file that cannot be shared between targets: a Worker
+ * takes its bindings from `cloudflare:workers`, a server is handed the core through Astro locals.
+ */
+export declare function pageHelper(config: ProjectConfig): string;
+export declare function wranglerConfig(config: ProjectConfig): string;
+/** The Worker's Trokky wiring: which adapters are imported is the composition, literally. */
+export declare function workersCore(config: ProjectConfig): string;
+export declare function workersEntry(config: ProjectConfig): string;
+export declare function nodeEntry(config: ProjectConfig): string;
+export declare function trokkyConfig(config: ProjectConfig): string;
+export declare function envExample(config: ProjectConfig): string;
+export declare function tsconfig(config: ProjectConfig): string;