@toist/in 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to `@toist/in` are recorded here.
+
+## 0.2.0 — 2026-05-05
+
+Initial release. Scaffold CLI for new toist instances.
+
+- `bunx @toist/in <path>` writes a fresh instance directory at `<path>`
+  with `start.ts`, `kinds/custom.ts`, `pipelines/`, `resources/`, `data/`,
+  `README.md`, and a default `.gitignore`.
+- Embedded templates ship with the package — no network calls during
+  scaffold.
+- Prints a suggested `package.json` snippet to stdout for the host to merge.
+- First release shipped together with `@toist/{spec,ui,run}@0.2.0` — the
+  rebrand from `@2121/*` (abandoned Gitea private registry) to `@toist/*`
+  on npmjs.com.

package/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "@toist/in",
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Scaffold a new toist instance: bunx @toist/in <path>",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "toist-in": "./src/index.ts"
+  },
+  "files": ["src/", "templates/", "CHANGELOG.md"]
+}

package/src/index.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env bun
+// 2121 toist
+// @toist/in — scaffold a new toist instance.
+//
+// Usage: bunx @toist/in <path>
+//
+// Writes a fresh instance directory at <path> with start.ts, kinds/,
+// pipelines/, resources/, data/, README.md, and .gitignore. Prints a
+// suggested package.json snippet to stdout for the host to merge.
+
+import { scaffold } from "./scaffold.ts"
+
+const args = process.argv.slice(2)
+const target = args[0]
+
+if (!target || target === "--help" || target === "-h") {
+  console.log("bunx @toist/in <path>     scaffold a new toist instance at <path>")
+  console.log("")
+  console.log("Full docs: https://toist.in")
+  process.exit(target ? 0 : 1)
+}
+
+await scaffold(target)

package/src/scaffold.ts

@@ -0,0 +1,68 @@
+// 2121 toist
+// Scaffold logic for @toist/in. Recursively copies templates/default/* into
+// the target directory, with two special filename rules:
+//
+//   - `_gitignore` -> `.gitignore` (npm strips real .gitignore files at publish
+//     time, so the templates ship them prefixed with an underscore)
+//   - `_package-snippet.json` is NOT copied — it is read and printed to stdout
+//     so the host can merge it into their existing package.json
+//
+// Templates live in `<package>/templates/default/`, relative to this file's
+// runtime location. Works whether the package is consumed as a workspace
+// link (in this repo) or from node_modules (in a host repo).
+
+import { mkdir, copyFile, readdir, stat, readFile } from "node:fs/promises"
+import { existsSync } from "node:fs"
+import { dirname, join, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const __dir         = dirname(fileURLToPath(import.meta.url))
+const TEMPLATE_DIR  = resolve(__dir, "..", "templates", "default")
+const SNIPPET_FILE  = "_package-snippet.json"
+const GITIGNORE_TPL = "_gitignore"
+
+export async function scaffold(target: string): Promise<void> {
+  const dest = resolve(process.cwd(), target)
+
+  if (existsSync(dest)) {
+    const entries = await readdir(dest)
+    if (entries.length > 0) {
+      console.error(`Target directory '${dest}' is not empty. Aborting.`)
+      process.exit(1)
+    }
+  } else {
+    await mkdir(dest, { recursive: true })
+  }
+
+  await copyTree(TEMPLATE_DIR, dest)
+
+  const snippet = await readFile(join(TEMPLATE_DIR, SNIPPET_FILE), "utf8")
+
+  console.log(`\nScaffolded toist instance at ${dest}\n`)
+  console.log(`Add to your package.json (or create one at ${target}/package.json):`)
+  console.log("")
+  console.log(snippet)
+  console.log("Then:")
+  console.log(`  cd ${target}`)
+  console.log(`  bun install`)
+  console.log(`  bun start.ts`)
+  console.log("")
+  console.log(`Full docs: https://toist.in`)
+  console.log("")
+}
+
+async function copyTree(src: string, dest: string): Promise<void> {
+  for (const entry of await readdir(src)) {
+    if (entry === SNIPPET_FILE) continue   // printed, not copied
+    const srcPath  = join(src, entry)
+    const destName = entry === GITIGNORE_TPL ? ".gitignore" : entry
+    const destPath = join(dest, destName)
+    const info     = await stat(srcPath)
+    if (info.isDirectory()) {
+      await mkdir(destPath, { recursive: true })
+      await copyTree(srcPath, destPath)
+    } else {
+      await copyFile(srcPath, destPath)
+    }
+  }
+}

package/templates/default/README.md

@@ -0,0 +1,23 @@
+# my-toist-instance
+
+Generated with [`bunx @toist/in`](https://toist.in).
+
+## First run
+
+1. Add the suggested deps to your `package.json` (printed by the scaffold output).
+2. `bun install`
+3. `bun start.ts` — runner boots on `http://localhost:3000`.
+
+Open `http://localhost:3000` to use the UI.
+
+## Layout
+
+- `start.ts` — bootstrap; calls `startRunner` from `@toist/run`
+- `kinds/custom.ts` — register your domain-specific kinds here
+- `pipelines/*.yaml` — pipeline definitions (per pipeline-spec)
+- `resources/*.yaml` — resource definitions (per resource-spec)
+- `data/` — runtime SQLite databases (gitignored)
+
+## More
+
+Full quickstart and docs: https://toist.in

package/templates/default/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+bun.lock
+data/*.db
+data/*.db-shm
+data/*.db-wal
+data/.lock/
+.platform/

package/templates/default/_package-snippet.json

@@ -0,0 +1,13 @@
+{
+  "name": "my-toist-instance",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "start": "bun start.ts",
+    "dev":   "bun --watch start.ts"
+  },
+  "dependencies": {
+    "@toist/run":  "^0.2.0",
+    "@toist/spec": "^0.2.0"
+  }
+}

package/templates/default/kinds/custom.ts

@@ -0,0 +1,23 @@
+// 2121 toist — register your domain-specific kinds here.
+//
+// Each export should be a NodeKind<P, I>. See the @toist/run built-ins for
+// reference shapes, and pipeline-spec / kind-spec at https://toist.in for
+// the full contract.
+//
+// Example:
+//
+//   import type { NodeKind } from "@toist/spec"
+//
+//   export const greet: NodeKind<{ name: string }, { msg: string }> = {
+//     id: "demo.greet",
+//     params: { name: { type: "string", required: true } },
+//     async execute(ctx) {
+//       return { msg: `Hello, ${ctx.params.name}!` }
+//     },
+//   }
+//
+// Then in start.ts:
+//   import * as customKinds from "./kinds/custom.ts"
+//   register(...Object.values(customKinds))
+
+export {}

package/templates/default/start.ts

@@ -0,0 +1,14 @@
+// 2121 toist instance bootstrap.
+// See https://toist.in for the full quickstart.
+
+import { startRunner } from "@toist/run"
+
+// Uncomment to register domain-specific kinds:
+// import { register } from "@toist/run"
+// import * as customKinds from "./kinds/custom.ts"
+// register(...Object.values(customKinds))
+
+await startRunner({
+  port:    Number(process.env.PORT ?? 3000),
+  rootDir: import.meta.dir,
+})