create-objectstack 17.0.0-rc.6 → 17.1.0

package/CHANGELOG.md

@@ -1,5 +1,355 @@
 # create-objectstack
 
+## 17.1.0
+
+### Minor Changes
+
+- 1eb28a1: Retire the five remote content templates from the scaffolder's catalog.
+  
+  `todo`, `compliance`, `content`, `contracts` and `procurement` were delisted
+  from the official ObjectStack template marketplace and are no longer
+  maintained, but the CLI carried its own hardcoded catalog and never learned
+  that: `--help` recommended all five by name with marketing descriptions, and
+  the `Available:` line on a bad `-t` offered them too.
+  
+  - `blank` (bundled, offline) is now the whole catalog, so the help text
+    advertises only what is actually supported.
+  - Asking for one of the five by name — `-t todo` in an old script or tutorial —
+    is refused with a message that says the template was retired, instead of the
+    generic "Unknown template" error that reads as a typo.
+  - The GitHub tarball-fetch path that served the remote templates is removed
+    along with its `tar` dependency; nothing else reached it.
+  
+  Note this corrects the catalog at HEAD only. Already-published versions keep
+  advertising the retired templates until a new version of `create-objectstack`
+  is released.
+
+### Patch Changes
+
+- 4906c90: Fix scaffolded projects describing themselves as the blank template (#9263)
+  
+  `rewriteProjectIdentity` rewrote `id` / `namespace` / `name` in both
+  `objectstack.config.ts` and `objectstack.manifest.json` from the project name,
+  but left `description` untouched — every scaffolded project carried the blank
+  template's own line verbatim ("Minimal ObjectStack environment — a clean
+  slate for building."), confidently wrong rather than empty, and printed by
+  the first command the getting-started flow tells people to run (`os
+  validate`).
+  
+  The scaffolder now drops `description` from both files instead of rewriting
+  it. There is nothing but the project name to derive a replacement from, and a
+  name-derived sentence (e.g. "Support Desk — an ObjectStack environment.")
+  would be a bare restatement of the `name`/`displayName` row already shown —
+  worse than no sentence at all. `os validate` already omits the description
+  line entirely when the field is unset, so a freshly scaffolded project now
+  prints cleanly:
+  
+  ```
+    Support Desk v0.1.0
+  ```
+  
+  instead of
+  
+  ```
+    Support Desk v0.1.0
+    Minimal ObjectStack environment — a clean slate for building.
+  ```
+- f2f09e4: fix(create-objectstack): the scaffolded Dockerfile pins the runtime image to the CLI that builds the artifact, instead of `latest` under a comment saying to pin (#9017)
+  
+  `src/templates/blank/Dockerfile` shipped `FROM ghcr.io/objectstack-ai/objectstack:latest`
+  directly beneath a comment instructing the reader to "pin the tag to the
+  `@objectstack/cli` version in your package.json so the runtime matches the CLI that built
+  the artifact" — an instruction the scaffold itself did not follow. Every app made with
+  `npx create-objectstack` shipped that contradiction from day one, and `docker/README.md`'s
+  tag table already scopes `latest` to quick starts while documenting `X.Y.Z` as the
+  production pin.
+  
+  Measured on scaffolded output rather than the template's bytes, before the fix:
+  
+  ```
+  emitted package.json cli range : ^17.0.0
+  emitted Dockerfile FROM        : FROM ghcr.io/objectstack-ai/objectstack:latest
+  agreement (tag vs cli range)   : DISAGREE
+  ```
+  
+  **The tag is resolved after `install`, from the installed CLI — not from the generated
+  `package.json`.** That file carries a caret RANGE, and the two are not interchangeable:
+  npm resolves `^17.0.0` to the newest 17.x, so pinning the range's floor would ship a
+  runtime image *older* than the CLI that built the artifact — breaking the same promise in
+  a new way. The rolling `:17` tag does match the range's float window but is exactly what
+  the tag table tells production not to use. The resolved version is the only value that
+  makes the sentence true, and it is the rule the repo already applies for this purpose in
+  `.github/workflows/scaffold-e2e.yml` ("Pin the runtime's CLI to the SAME version the
+  generated project actually resolved to — NOT a hardcoded `latest`").
+  
+  **Both halves move together.** Pinning the line while leaving an imperative to pin by hand
+  would relocate the contradiction rather than remove it, so the comment above the `FROM`
+  line is replaced in the same rewrite. With `--skip-install` there is no resolved version:
+  the tag stays `latest` and the comment keeps telling the reader to pin — which is true on
+  that path, because there the user really must do it by hand.
+  
+  The regression proof asserts on **scaffolded output**, never on the template: it scaffolds
+  with the real copy/sync/pin path, plants an installed CLI whose version is deliberately
+  *not* the range's floor (the normal case, and the one that a package.json-derived tag
+  would get wrong), and checks the emitted `FROM` tag against the emitted `package.json`
+  range with a satisfies-check rather than equality.
+  
+  `.github/workflows/scaffold-e2e.yml` now reads the tag it builds its local runtime image
+  under **out of the generated Dockerfile** instead of hardcoding `:latest`. Those were two
+  hand-matched literals; had they skewed, Docker would have quietly pulled the last
+  published image instead of the one built from this checkout, and the job's own stated
+  hermeticity would have been false while it stayed green.
+- 0a5adba: fix(create-objectstack): the blank template's `specVersion` stops shipping eleven majors stale, and the version-time sync covers every declared surface on every template (#9264)
+  
+  The one bundled template declared the platform it targets in **two** places that
+  disagreed by eleven majors:
+  
+  | file | key | was |
+  |:--|:--|:--|
+  | `objectstack.manifest.json` | `specVersion` | `^6.0.0` |
+  | `objectstack.config.ts` | `engines.protocol` | `^17` |
+  
+  `scripts/sync-template-versions.mjs` re-stamped the config key and the template's
+  `@objectstack/*` dependency ranges, and **never opened the manifest at all**. So
+  `engines.protocol` tracked every major bump while `specVersion` sat at the value
+  it held when the script was written — and a green `sync-template-versions` run
+  was never evidence about it, because the script's failure mode was loud for the
+  keys it covered and mute for the key it did not.
+  
+  **This is not confined to the registry contract.** `create-objectstack` copies
+  the manifest into every scaffolded project, rewriting `name`, `displayName` and
+  `namespace` and dropping `description` — it has never touched `specVersion`. So
+  every project scaffolded since v7 was stamped with a `^6.0.0` spec range while
+  installing `@objectstack/spec@^17.0.0`.
+  
+  **The two keys are two facts, and the fix keeps them apart.** `engines.protocol`
+  is the ADR-0087 D1 runtime handshake range and carries the protocol major
+  (`^17`). `specVersion` is documented by `TemplateManifestSchema` as the
+  "Compatible `@objectstack/spec` semver range" and carries the package range
+  (`^17.0.0`) — the same value the script already writes into the template's own
+  `@objectstack/spec` dependency, so the manifest and the `package.json` now state
+  one fact once. They agree on the major only because the spec package's major and
+  the protocol major are kept in lockstep; they are stamped from two different
+  values.
+  
+  Deleting the key was not available: `specVersion` is **required** by
+  `TemplateManifestSchema`, and every shipped manifest is parsed against it by
+  `check:template-manifests`.
+  
+  **Two structural changes, because one-key-one-file coverage is what let this
+  sit:**
+  
+  - the sync script's file list is now **discovered**, not hard-coded — templates
+    are found by walking `src/templates/`, the same way `check-template-manifests`
+    finds the manifests it parses, so a second template is covered on the day it
+    lands;
+  - **every stamp is required**. A template whose file is missing, whose stamp is
+    absent, or whose `package.json` declares no `@objectstack/*` dependency is a
+    hard failure naming the path — never a skip. A skipped stamp is
+    indistinguishable from a synced one in the log, which is the invisibility this
+    fixes.
+  
+  The manifest is rewritten as **text** rather than parsed and re-serialized:
+  `objectstack.manifest.json` keeps `scaffold.variables` compact on one line, and
+  `JSON.stringify(…, null, 2)` would reformat unrelated structure on every release.
+  
+  CI coverage lands as four per-template ratchets in `template-consistency.test.ts`,
+  generalized off `blank` onto the same directory walk — including the invariant
+  that catches this exact class: the manifest's `specVersion` must equal the
+  `@objectstack/spec` range the template actually installs. Either file alone can
+  be self-consistently stale; only comparing them catches a stamp that covered one
+  and not the other.
+
+## 17.0.0
+
+### Major Changes
+
+- e47b342: feat!: require Node.js 22 — promise the runtime we actually test (#3825)
+
+  Every published package declared `engines.node: ">=18.0.0"`. **Node 18 reached
+  end-of-life on 2025-04-30 and Node 20 on 2026-04-30**, so the compatibility
+  promise covered two runtimes nobody patches — and, after #3830 moved CI to Node
+  22, two runtimes nothing in this repo verifies.
+
+  That left the promise and the evidence with **no overlap at all**:
+
+  |                                                                                                 | Node version |
+  | ----------------------------------------------------------------------------------------------- | ------------ |
+  | What CI validates every PR on                                                                   | **22**       |
+  | What `release.yml` publishes from                                                               | **22**       |
+  | What every shipped Docker image runs (`docker/Dockerfile`, `blank` template, self-hosting docs) | **22**       |
+  | What `engines.node` promised users                                                              | **>=18**     |
+
+  `engines.node` is now `>=22.0.0` across all 50 manifests. This is the honest
+  floor: it is the only runtime the packages are built, tested and shipped on.
+
+  ## Migration
+
+  **If you are on Node 22 or newer, nothing changes.** Node 24 (Active LTS since
+  2025-10-28) and Node 26 both satisfy the new range.
+
+  If you are on Node 18 or 20, upgrade to Node 22+. Both are past end-of-life and
+  receive no security patches:
+
+  ```bash
+  nvm install 22 && nvm use 22
+  ```
+
+  npm and pnpm surface an unsatisfied `engines` as an **`EBADENGINE` warning**, not
+  a hard failure, so an existing install will not break the moment you upgrade —
+  but the package is no longer tested on that runtime, and the failures are the
+  kind that do not announce themselves. #3812 is the worked example: a native
+  dependency whose `engines` required a newer Node loaded anyway on the older one
+  and then killed the test worker at the process level, with no JS error and a
+  summary that still said "passed".
+
+  If your CI pins Node, pin it to 22 as well — running your gates on a runtime
+  your dependencies no longer support is exactly the split this change closes.
+
+  ## Also updated
+
+  The "Node 18+" prerequisite was restated in ten user-facing places
+  (`README.md`, `CONTRIBUTING.md`, the getting-started and deployment docs, the
+  todo example, and the `objectstack-platform` skill's `compatibility` field).
+  All now say 22. Changelogs and ADRs are historical records and were left alone.
+
+### Patch Changes
+
+- 9f060e5: chore(deps)!: better-auth 1.7.0-rc.2 (account identity restructuring) + the
+  production-dependency batch from #3517
+
+  **better-auth 1.7.0-rc.1 → 1.7.0-rc.2** across the family (`better-auth`,
+  `@better-auth/core`, `@better-auth/oauth-provider`, `@better-auth/sso`, and the
+  adapter/telemetry overrides). `@better-auth/scim` deliberately stays on
+  1.7.0-rc.1 — rc.2 replaces its whole model (code-defined connections; the
+  `scimProvider` model and the generate-token endpoint are gone), which is a
+  feature migration, not a version bump. Its peer range accepts rc.2 core, and the
+  advisory that forced the original pin (GHSA-j8v8-g9cx-5qf4) is still fixed.
+
+  **BREAKING — account identity.** better-auth renamed `account.accountId` to
+  `account.providerAccountId` and added a REQUIRED `account.issuer`; sign-in now
+  resolves accounts by `(issuer, providerAccountId)`.
+
+  - FROM `fields: { accountId: 'account_id' }` → TO
+    `fields: { issuer: 'issuer', providerAccountId: 'account_id' }`. The provider
+    account id keeps its `account_id` column — only the better-auth-side name
+    moved — and `sys_account` gains an `issuer` column.
+  - FROM `internalAdapter.createAccount({ providerId, accountId, … })` → TO
+    `createAccount({ providerId, issuer, providerAccountId, … })`. A local
+    password account carries the issuer better-auth mints for itself,
+    `local:credential`.
+  - FROM `client.auth.accounts.unlink({ providerId, accountId })` → TO
+    `unlink({ accountId })`, where `accountId` is now the account ROW id (the `id`
+    from `accounts.list()`), matching better-auth's narrowed body.
+    `accounts.list()` returns `issuer` + `providerAccountId` in place of
+    `accountId`.
+
+  **Existing deployments:** rows written before 1.7 have no issuer and are
+  invisible to sign-in until stamped. The auth plugin now runs an idempotent
+  boot-time backfill that stamps what it can derive — `local:credential` for
+  password accounts, `local:oauth:<providerId>` for configured social providers,
+  and the registered IdP's real `iss` from `sys_sso_provider` for federated ones.
+  Accounts from a federated IdP that is no longer registered cannot be derived;
+  they are logged with their provider id and row count rather than guessed, and
+  those users cannot sign in through that provider until the row is stamped with
+  the IdP's issuer or removed so a fresh login re-links it.
+
+  **Also required by 1.7:** `SecondaryStorage` gained two mandatory methods, both
+  now implemented over the kernel cache service — `getAndDelete` (single-use
+  verification values) and `increment` (fixed-window rate-limit counter;
+  `rateLimit.storage: 'secondary-storage'` throws at boot without it).
+
+  The rest of #3517's production-dependency batch rides along: `@oclif/core`
+  4.13.0, `@hono/node-server` 2.0.12, `hono` 4.12.32, `tar` 7.5.22, `jose` 6.2.4,
+  `pinyin-pro` 3.28.2, plus the private docs app's fumadocs/next/react bumps.
+
+- 2e836de: chore(packaging): CHANGELOG.md ships in every npm tarball (#4261)
+
+  The AGENTS.md post-task checklist requires breaking changesets to carry their
+  FROM → TO migration because "this text ships to consumers as `CHANGELOG.md`
+  inside the npm package and is what an upgrading agent greps after the tombstone
+  error." That delivery path was severed for 68 of the 69 publishable packages:
+  npm packs `package.json` / `README*` / `LICENSE*` unconditionally but — unlike
+  older npm versions — not `CHANGELOG.md`, and the canonical
+  `"files": ["dist", "README.md"]` whitelist never named it. Measured on npm
+  10.9.7: `npm pack --dry-run` on `@objectstack/types` shipped 3 files while its
+  70KB `CHANGELOG.md` stayed behind. Only `@objectstack/spec` listed it
+  explicitly.
+
+  The tombstone-error scenario is precisely the one where the repo is out of
+  reach — the upgrading agent has `node_modules` and nothing else — so the
+  migration text has to ride in the tarball. Every publishable package now
+  declares `CHANGELOG.md` in `files`, and the canonical whitelist is
+  `["dist", "README.md", "CHANGELOG.md"]`.
+
+  The other half is the gate: `check:published-files` gains a fifth invariant,
+  COMPLETE — a whitelist that fails to cover `CHANGELOG.md` fails the
+  always-required lint job, so the next package cannot silently sever the path
+  again. `@objectstack/spec`'s per-package EXTRA_ENTRIES exemption dissolves
+  into the canonical set.
+
+  Consumer-visible change: one more file per install (the package's changelog,
+  e.g. 70.8KB for `@objectstack/types`), and `grep -r "removed key"
+node_modules/@objectstack/*/CHANGELOG.md` now finds the migration it was
+  promised.
+
+- 4e9e184: chore(deps): OSV security batch — bump tar to ^7.5.21 (GHSA-r292-9mhp-454m) and
+  js-yaml to ^5.2.2 (GHSA-pm4m-ph32-ghv5)
+
+  Both are declared-range bumps to the patched releases, so downstream installs
+  resolve the fixed versions from the published manifests, not just this
+  workspace's lockfile. The same batch clears the remaining transitive advisories
+  (next 16.2.11 in apps/docs; workspace overrides for brace-expansion, sharp,
+  react-router, @sveltejs/kit, @hono/node-server) — those live in pnpm-workspace.yaml
+  and the private docs app, which do not ship.
+
+- 8d41998: fix(create-objectstack): scaffolding a remote template no longer produces a project that cannot build (#4926)
+
+  `npx create-objectstack@latest my-app -t todo` (and `compliance`, `content`,
+  `contracts`, `procurement`) generated a project that failed `objectstack build`
+  immediately — 5 of the 6 offered templates. Only the bundled `blank` worked.
+
+  The scaffolder read the template's original namespace from
+  `objectstack.manifest.json`, and that filename names two different documents.
+  The bundled template's is app-shaped and carries `namespace`; a remote
+  template's is the template-registry document
+  (`$schema: …/template-manifest.json`) and carries none — its namespace lives
+  only in `objectstack.config.ts`. So the value came back `undefined` for every
+  remote template and the object-name rewrite was skipped, while the config's
+  `namespace:` was rewritten anyway. The result was `namespace: 'my_app'` sitting
+  next to `name: 'todo_task'`, which the `${namespace}_${shortName}` rule rejects.
+  Across the five templates, 74 object names were left unrewritten.
+
+  `objectstack.config.ts` is now the authority for the template namespace (it
+  holds the very literal the scaffolder overwrites, so the two cannot disagree),
+  with the manifest as fallback. The rewrite also verifies itself: any surviving
+  stale prefix throws at the scaffold, naming the files and lines, instead of
+  surfacing as a build failure on the user's first command.
+
+- 7309c81: chore(cli,create-objectstack): scaffolds no longer name a driver (#4065)
+
+  `os init` and the `create-objectstack` blank template both listed
+  `@objectstack/driver-memory` in the generated `dependencies`. It was the only
+  driver named, which read as an endorsement — "this is the driver your app runs
+  on" — when it is in fact the **last-resort rung** of the dev step-down (native
+  `better-sqlite3` → WASM SQLite → mingo). A new project's first impression of the
+  data layer should not be the engine that enforces no primary keys, no
+  uniqueness, no `NOT NULL` and no column types.
+
+  It was also redundant: `@objectstack/runtime` already depends on `driver-sql`,
+  `driver-sqlite-wasm` and `driver-memory`, and every script in both scaffolds runs
+  through the CLI, which carries all four. Removing the line changes nothing a
+  generated project can do — `objectstack dev` still resolves SQLite by default,
+  and `OS_DATABASE_URL` still selects Postgres / MySQL / MongoDB.
+
+  Docs updated to match: the "packages you depend on" table in _Your first project_
+  no longer lists a driver row (it now says where drivers come from), and the
+  Memory Driver section of _Database Drivers_ documents the opt-in persistence
+  default, carries a migration callout for the old `'auto'` behaviour, and points
+  test authors at in-memory SQLite. That section also claimed "Data is lost when
+  the process exits", which was simply false while `'auto'` was the default — it
+  wrote a file into the working directory.
+
 ## 17.0.0-rc.6
 
 ## 17.0.0-rc.5

package/README.md

@@ -27,16 +27,14 @@ npx create-objectstack my-app --skip-install
 | Template | Source | Description |
 | --- | --- | --- |
 | `blank` *(default)* | bundled (offline) | Minimal starter — one object, REST API, ready to extend |
-| `todo` | remote | Universal task & project management starter |
-| `compliance` | remote | Compliance posture & evidence management (SOC2 / ISO27001) |
-| `content` | remote | Content marketing pipeline — editorial calendar & channel ROI |
-| `contracts` | remote | Post-signature CLM — approvals, obligations, renewals |
-| `procurement` | remote | Source-to-pay — vendors, POs, receipts, invoice matching |
-
-Remote templates are fetched from
-[`objectstack-ai/templates`](https://github.com/objectstack-ai/templates) at
-scaffold time and require network access; `blank` is bundled and always works
-offline.
+
+`blank` is bundled inside the npm package, so scaffolding never needs network
+access.
+
+The remote content templates (`todo`, `compliance`, `content`, `contracts`,
+`procurement`) have been **retired** — they were delisted from the ObjectStack
+template marketplace and are no longer maintained. Asking for one by name tells
+you so rather than failing as an unknown template.
 
 ## Options
 

package/dist/index.js

@@ -1,16 +1,10 @@
 // src/index.ts
 import { Command } from "commander";
 import chalk from "chalk";
-import fs3 from "fs";
-import path3 from "path";
-import os from "os";
+import fs4 from "fs";
+import path4 from "path";
 import { execSync } from "child_process";
 import { fileURLToPath } from "url";
-import { pipeline } from "stream/promises";
-import { createGunzip } from "zlib";
-import { createWriteStream, createReadStream } from "fs";
-import { mkdtemp, rm } from "fs/promises";
-import * as tar from "tar";
 
 // src/pkg-utils.ts
 function syncObjectStackDeps(pkg, version) {
@@ -114,39 +108,94 @@ function findStaleNamespacePrefixes(dir, oldNs) {
   return stale;
 }
 
-// src/index.ts
-var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = path3.dirname(__filename2);
-var BUNDLED_TEMPLATES_DIR = path3.resolve(__dirname2, "templates");
-var REMOTE_REPO = "objectstack-ai/templates";
-var REMOTE_BRANCH = "main";
-var REMOTE_TARBALL_URL = `https://codeload.github.com/${REMOTE_REPO}/tar.gz/refs/heads/${REMOTE_BRANCH}`;
+// src/template-registry.ts
 var TEMPLATES = {
   blank: {
     description: "Minimal starter \u2014 one object, REST API, ready to extend",
     source: { kind: "bundled", dir: "blank" }
-  },
-  todo: {
-    description: "Universal task & project management starter",
-    source: { kind: "remote", pkg: "todo" }
-  },
-  compliance: {
-    description: "Compliance posture & evidence management (SOC2 / ISO27001)",
-    source: { kind: "remote", pkg: "compliance" }
-  },
-  content: {
-    description: "Content marketing pipeline \u2014 editorial calendar & channel ROI",
-    source: { kind: "remote", pkg: "content" }
-  },
-  contracts: {
-    description: "Post-signature CLM \u2014 approvals, obligations, renewals",
-    source: { kind: "remote", pkg: "contracts" }
-  },
-  procurement: {
-    description: "Source-to-pay \u2014 vendors, POs, receipts, invoice matching",
-    source: { kind: "remote", pkg: "procurement" }
   }
 };
+var RETIRED_TEMPLATES = [
+  "todo",
+  "compliance",
+  "content",
+  "contracts",
+  "procurement"
+];
+function lookupTemplate(name) {
+  const template = TEMPLATES[name];
+  if (template) return { kind: "found", name, template };
+  if (RETIRED_TEMPLATES.includes(name)) return { kind: "retired", name };
+  return { kind: "unknown", name };
+}
+function templateNames() {
+  return Object.keys(TEMPLATES);
+}
+
+// src/runtime-image.ts
+import fs3 from "fs";
+import path3 from "path";
+var RUNTIME_FROM_RE = /^FROM ghcr\.io\/objectstack-ai\/objectstack:([A-Za-z0-9_][A-Za-z0-9_.+-]*)[ \t]*$/;
+var PINNABLE_VERSION_RE = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/;
+var PROSE_COMMENT_RE = /^#[ \t]+\S/;
+function readResolvedCliVersion(targetDir) {
+  const pkgPath = path3.join(
+    targetDir,
+    "node_modules",
+    "@objectstack",
+    "cli",
+    "package.json"
+  );
+  try {
+    const version = JSON.parse(fs3.readFileSync(pkgPath, "utf8")).version;
+    return typeof version === "string" && PINNABLE_VERSION_RE.test(version) ? version : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function pinnedComment(version) {
+  return [
+    "# Pinned at scaffold time to the @objectstack/cli version this project",
+    "# resolved, so the runtime runs the same CLI that built your artifact.",
+    "# Move both together when you upgrade \u2014 see docker/README.md tag table.",
+    `FROM ghcr.io/objectstack-ai/objectstack:${version}`
+  ];
+}
+function pinRuntimeImage(targetDir, version) {
+  if (!PINNABLE_VERSION_RE.test(version)) {
+    return { pinned: false, reason: `'${version}' is not a pinnable version` };
+  }
+  const dockerfile = path3.join(targetDir, "Dockerfile");
+  let text;
+  try {
+    text = fs3.readFileSync(dockerfile, "utf8");
+  } catch {
+    return { pinned: false, reason: "no Dockerfile in the scaffolded project" };
+  }
+  const lines = text.split("\n");
+  const fromIdx = lines.findIndex((line) => RUNTIME_FROM_RE.test(line));
+  if (fromIdx === -1) {
+    return {
+      pinned: false,
+      reason: "no `FROM ghcr.io/objectstack-ai/objectstack:<tag>` line found"
+    };
+  }
+  let start = fromIdx;
+  while (start > 0 && PROSE_COMMENT_RE.test(lines[start - 1])) start--;
+  lines.splice(start, fromIdx - start + 1, ...pinnedComment(version));
+  const pinnedText = lines.join("\n");
+  const check = pinnedText.split("\n").map((line) => RUNTIME_FROM_RE.exec(line)).find((match) => match !== null);
+  if (!check || check[1] !== version) {
+    return { pinned: false, reason: "rewrite did not produce the pinned tag" };
+  }
+  fs3.writeFileSync(dockerfile, pinnedText);
+  return { pinned: true, tag: version };
+}
+
+// src/index.ts
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = path4.dirname(__filename2);
+var BUNDLED_TEMPLATES_DIR = path4.resolve(__dirname2, "templates");
 function toTitleCase(str) {
   return str.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
 }
@@ -163,8 +212,8 @@ function sanitizeNamespace(name) {
 }
 function readCliVersion() {
   try {
-    const pkgPath = path3.resolve(__dirname2, "..", "package.json");
-    const pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf8"));
+    const pkgPath = path4.resolve(__dirname2, "..", "package.json");
+    const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf8"));
     return String(pkg.version || "0.0.0");
   } catch {
     return "0.0.0";
@@ -199,98 +248,50 @@ function detectPackageManager() {
   }
 }
 function loadBundled(templateDir, targetDir) {
-  const src = path3.join(BUNDLED_TEMPLATES_DIR, templateDir);
-  if (!fs3.existsSync(src)) {
+  const src = path4.join(BUNDLED_TEMPLATES_DIR, templateDir);
+  if (!fs4.existsSync(src)) {
     throw new Error(`Bundled template missing on disk: ${src}`);
   }
   const collected = [];
   copyDir(src, targetDir, collected);
   return collected;
 }
-async function downloadTarball(url, destFile) {
-  const res = await fetch(url, { redirect: "follow" });
-  if (!res.ok || !res.body) {
-    throw new Error(`Download failed: ${url} (${res.status})`);
-  }
-  const out = createWriteStream(destFile);
-  for await (const chunk of res.body) {
-    out.write(chunk);
-  }
-  await new Promise((resolve, reject) => {
-    out.end((err) => err ? reject(err) : resolve());
-  });
-}
-async function loadRemote(pkgName, targetDir) {
-  const tmp = await mkdtemp(path3.join(os.tmpdir(), "create-objectstack-"));
-  try {
-    const tarball = path3.join(tmp, "templates.tar.gz");
-    printStep(`Fetching template "${pkgName}" from ${REMOTE_REPO}@${REMOTE_BRANCH}\u2026`);
-    await downloadTarball(REMOTE_TARBALL_URL, tarball);
-    fs3.mkdirSync(targetDir, { recursive: true });
-    const collected = [];
-    await pipeline(
-      createReadStream(tarball),
-      createGunzip(),
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      tar.extract({
-        cwd: targetDir,
-        strip: 3,
-        filter: (p) => {
-          const parts = p.split("/");
-          return parts[1] === "packages" && parts[2] === pkgName && parts.length > 3;
-        },
-        onentry: (entry) => {
-          if (entry.type === "File") {
-            const parts = entry.path.split("/").slice(3);
-            if (parts.length > 0) collected.push(parts.join("/"));
-          }
-        }
-      })
-    );
-    if (collected.length === 0) {
-      throw new Error(
-        `Template "${pkgName}" not found in ${REMOTE_REPO}@${REMOTE_BRANCH} (expected packages/${pkgName}/).`
-      );
-    }
-    return collected;
-  } finally {
-    await rm(tmp, { recursive: true, force: true });
-  }
-}
 function rewriteProjectIdentity(targetDir, projectName, namespace) {
   const title = toTitleCase(projectName);
   const templateNamespace = readTemplateNamespace(targetDir);
-  const pkgPath = path3.join(targetDir, "package.json");
-  if (fs3.existsSync(pkgPath)) {
+  const pkgPath = path4.join(targetDir, "package.json");
+  if (fs4.existsSync(pkgPath)) {
     try {
-      const pkg = JSON.parse(fs3.readFileSync(pkgPath, "utf8"));
+      const pkg = JSON.parse(fs4.readFileSync(pkgPath, "utf8"));
       pkg.name = projectName;
       syncObjectStackDeps(pkg, readCliVersion());
-      fs3.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+      fs4.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
     } catch {
     }
   }
-  const manifestPath = path3.join(targetDir, "objectstack.manifest.json");
-  if (fs3.existsSync(manifestPath)) {
+  const manifestPath = path4.join(targetDir, "objectstack.manifest.json");
+  if (fs4.existsSync(manifestPath)) {
     try {
-      const m = JSON.parse(fs3.readFileSync(manifestPath, "utf8"));
+      const m = JSON.parse(fs4.readFileSync(manifestPath, "utf8"));
       m.name = projectName;
       m.displayName = title;
       if ("namespace" in m) m.namespace = namespace;
-      fs3.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
+      delete m.description;
+      fs4.writeFileSync(manifestPath, JSON.stringify(m, null, 2) + "\n");
     } catch {
     }
   }
-  const configPath = path3.join(targetDir, "objectstack.config.ts");
-  if (fs3.existsSync(configPath)) {
-    let cfg = fs3.readFileSync(configPath, "utf8");
+  const configPath = path4.join(targetDir, "objectstack.config.ts");
+  if (fs4.existsSync(configPath)) {
+    let cfg = fs4.readFileSync(configPath, "utf8");
     cfg = cfg.replace(/(\bid:\s*)(['"`])[^'"`]*\2/, `$1$2${projectName}$2`);
     cfg = cfg.replace(/(\bnamespace:\s*)(['"`])[^'"`]*\2/, `$1$2${namespace}$2`);
     cfg = cfg.replace(/(\bname:\s*)(['"`])[^'"`]*\2/, `$1$2${title}$2`);
-    fs3.writeFileSync(configPath, cfg);
+    cfg = cfg.replace(/^[ \t]*description:\s*(['"`])[^'"`]*\1,?\r?\n/m, "");
+    fs4.writeFileSync(configPath, cfg);
   }
   if (templateNamespace && namespace !== templateNamespace) {
-    const srcDir = path3.join(targetDir, "src");
+    const srcDir = path4.join(targetDir, "src");
     rewriteObjectNamePrefix(srcDir, templateNamespace, namespace);
     const stale = findStaleNamespacePrefixes(srcDir, templateNamespace);
     if (stale.length > 0) {
@@ -304,77 +305,82 @@ The generated project would fail 'objectstack build' on the \${namespace}_\${sho
       );
     }
   }
-  const readmePath = path3.join(targetDir, "README.md");
-  if (fs3.existsSync(readmePath)) {
-    let md = fs3.readFileSync(readmePath, "utf8");
+  const readmePath = path4.join(targetDir, "README.md");
+  if (fs4.existsSync(readmePath)) {
+    let md = fs4.readFileSync(readmePath, "utf8");
     md = md.replace(/^#\s+.*$/m, `# ${title}`);
-    fs3.writeFileSync(readmePath, md);
+    fs4.writeFileSync(readmePath, md);
   }
   writeAgentGuides(targetDir, title, projectName);
 }
 function writeAgentGuides(targetDir, title, projectName) {
-  const templatePath = path3.join(BUNDLED_TEMPLATES_DIR, "AGENTS.md");
+  const templatePath = path4.join(BUNDLED_TEMPLATES_DIR, "AGENTS.md");
   let template;
   try {
-    template = fs3.readFileSync(templatePath, "utf8");
+    template = fs4.readFileSync(templatePath, "utf8");
   } catch (err) {
     if (err?.code === "ENOENT") return;
     throw err;
   }
   const rendered = template.replace(/\{\{PROJECT_TITLE\}\}/g, title).replace(/\{\{PROJECT_NAME\}\}/g, projectName);
-  writeIfAbsent(path3.join(targetDir, "AGENTS.md"), rendered);
-  const copilotPath = path3.join(targetDir, ".github", "copilot-instructions.md");
-  fs3.mkdirSync(path3.dirname(copilotPath), { recursive: true });
+  writeIfAbsent(path4.join(targetDir, "AGENTS.md"), rendered);
+  const copilotPath = path4.join(targetDir, ".github", "copilot-instructions.md");
+  fs4.mkdirSync(path4.dirname(copilotPath), { recursive: true });
   writeIfAbsent(copilotPath, rendered);
 }
 function writeIfAbsent(filePath, contents) {
   try {
-    fs3.writeFileSync(filePath, contents, { flag: "wx" });
+    fs4.writeFileSync(filePath, contents, { flag: "wx" });
   } catch (err) {
     if (err?.code !== "EEXIST") throw err;
   }
 }
 var program = new Command().name("create-objectstack").description("Create a new ObjectStack environment").version(readCliVersion()).argument("[name]", "Environment name (defaults to current directory name)").option(
   "-t, --template <template>",
-  `Template: ${Object.keys(TEMPLATES).join(", ")}`,
+  `Template: ${templateNames().join(", ")}`,
   "blank"
-).option("--skip-install", "Skip dependency installation").option("--skip-skills", "Skip installing ObjectStack AI skills").action(async (name, options) => {
+).option("--skip-install", "Skip dependency installation").option("--skip-skills", "Skip installing ObjectStack AI skills").action((name, options) => {
   console.log("");
   console.log(chalk.bold.cyan("  \u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557"));
   console.log(chalk.bold.cyan("  \u2551") + chalk.bold("   \u25C6 Create ObjectStack ") + chalk.dim("v6.x") + chalk.bold.cyan("       \u2551"));
   console.log(chalk.bold.cyan("  \u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D"));
   printHeader("New Environment");
-  const template = TEMPLATES[options.template];
-  if (!template) {
-    printError(`Unknown template: ${options.template}`);
-    console.log(chalk.dim(`  Available: ${Object.keys(TEMPLATES).join(", ")}`));
+  const lookup = lookupTemplate(options.template);
+  if (lookup.kind !== "found") {
+    if (lookup.kind === "retired") {
+      printError(`Template "${lookup.name}" has been retired and is no longer available.`);
+      console.log(
+        chalk.dim(
+          "  It was delisted from the ObjectStack template marketplace and is no longer maintained."
+        )
+      );
+    } else {
+      printError(`Unknown template: ${lookup.name}`);
+    }
+    console.log(chalk.dim(`  Available: ${templateNames().join(", ")}`));
     process.exit(1);
   }
+  const template = lookup.template;
   const cwd = process.cwd();
-  const projectName = name || path3.basename(cwd);
+  const projectName = name || path4.basename(cwd);
   const namespace = sanitizeNamespace(projectName);
-  const targetDir = name ? path3.resolve(cwd, name) : cwd;
+  const targetDir = name ? path4.resolve(cwd, name) : cwd;
   const isCurrentDir = targetDir === cwd;
   printKV("Environment", projectName);
   printKV("Namespace", namespace);
   printKV("Template", `${options.template} \u2014 ${template.description}`);
   printKV("Directory", targetDir);
   console.log("");
-  if (!isCurrentDir && fs3.existsSync(targetDir)) {
-    const existing = fs3.readdirSync(targetDir);
+  if (!isCurrentDir && fs4.existsSync(targetDir)) {
+    const existing = fs4.readdirSync(targetDir);
     if (existing.length > 0) {
       printError(`Directory already exists and is not empty: ${targetDir}`);
       process.exit(1);
     }
   }
   try {
-    fs3.mkdirSync(targetDir, { recursive: true });
-    let createdFiles;
-    if (template.source.kind === "bundled") {
-      createdFiles = loadBundled(template.source.dir, targetDir);
-    } else {
-      createdFiles = await loadRemote(template.source.pkg, targetDir);
-    }
+    fs4.mkdirSync(targetDir, { recursive: true });
+    const createdFiles = loadBundled(template.source.dir, targetDir);
     rewriteProjectIdentity(targetDir, projectName, namespace);
     console.log(chalk.bold("  Created files:"));
     for (const f of createdFiles.slice(0, 20)) {
@@ -386,14 +392,30 @@ var program = new Command().name("create-objectstack").description("Create a new
     console.log("");
     if (!options.skipInstall) {
       printStep("Installing dependencies...");
+      let installed = false;
       try {
         const pm = detectPackageManager();
         execSync(`${pm} install`, { stdio: "inherit", cwd: targetDir });
+        installed = true;
         console.log("");
       } catch {
         printWarning("Dependency installation failed. Run `npm install` manually.");
         console.log("");
       }
+      if (installed) {
+        const resolved = readResolvedCliVersion(targetDir);
+        if (resolved) {
+          const result = pinRuntimeImage(targetDir, resolved);
+          if (result.pinned) {
+            printSuccess(`Dockerfile runtime image pinned to ${result.tag}`);
+          } else {
+            printWarning(
+              `Could not pin the Dockerfile runtime image (${result.reason}); it still reads \`latest\` \u2014 pin it to ${resolved} before deploying.`
+            );
+          }
+          console.log("");
+        }
+      }
     }
     if (!options.skipInstall && !options.skipSkills) {
       printStep("Installing AI skills for your coding agent...");

package/dist/templates/blank/Dockerfile

@@ -20,9 +20,12 @@ RUN npx os build              # → dist/objectstack.json
 # ── Runtime: the official ObjectStack runtime image ──────────────────
 # Ships Node + @objectstack/cli with `os start`, a non-root user, the
 # /api/v1/health HEALTHCHECK, and OS_ARTIFACT_PATH/OS_PORT preset (port 8080)
-# — see docker/README.md in the framework repo. Pin the tag to the
-# @objectstack/cli version in your package.json so the runtime matches the
-# CLI that built the artifact.
+# — see docker/README.md in the framework repo.
+#
+# Dependencies were not installed while scaffolding, so the tag below could
+# not be resolved for you. `latest` floats to whatever release is newest,
+# which is unrelated to the @objectstack/cli your app resolves — pin it to
+# that version, the CLI that builds your artifact, before you deploy.
 FROM ghcr.io/objectstack-ai/objectstack:latest
 COPY --from=build --chown=node:node /app/dist/objectstack.json /srv/app/objectstack.json
 

package/dist/templates/blank/objectstack.manifest.json

@@ -2,7 +2,7 @@
   "$schema": "https://schemas.objectstack.dev/template-manifest.json",
   "name": "blank",
   "namespace": "blank",
-  "specVersion": "^6.0.0",
+  "specVersion": "^17.0.0",
   "displayName": "Blank Starter",
   "description": "Minimal ObjectStack environment with a single object — a clean slate for building.",
   "category": "starter",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-objectstack",
-  "version": "17.0.0-rc.6",
+  "version": "17.1.0",
   "description": "Create a new ObjectStack project — npx create-objectstack",
   "bin": {
     "create-objectstack": "./bin/create-objectstack.js"
@@ -16,11 +16,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "chalk": "^6.0.0",
-    "commander": "^15.0.0",
-    "tar": "^7.5.22"
+    "commander": "^15.0.0"
   },
   "devDependencies": {
-    "@types/node": "^26.1.2",
+    "@types/node": "^26.2.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"