release: prepare Flatbread 1.0 by tonyketcham · Pull Request #235 · FlatbreadLabs/flatbread

tonyketcham · 2026-07-29T10:45:10Z

Summary of changes

Prepare all 12 public packages for the stable 1.0.0 release. Package metadata now uses one version and Node floor, release assets match v1.0.0, and package dependencies resolve for clean installs.

Lead the docs with Effort Graph as Git-native memory for coding agents. Keep static relational content as a first-class use and GraphQL as one read interface. Add short release notes and the MIT license.

Remove unused Apollo 3 and GraphQL server packages from the published runtime. Update Apollo Server, GraphQL, GraphQL Code Generator, esbuild, and lodash-es to supported releases. Trim Proof's npm payload to its bins and built output. Make @flatbread/core declarations portable in strict clean installs.

Verification

pnpm verify
Packed all 12 npm packages at 1.0.0
Clean main Flatbread install: zero production audit findings
Strict NodeNext TypeScript consumer compile: pass
Packed Flatbread CLI/import smoke: pass
Packed Proof dry command check: pass

Known upstream limits

Installing all 12 packages reports seven audit entries with no compatible upstream fix. Proof inherits them through @cursor/sdk and undici@5; resolver-svimg inherits them through svimg and sharp. Neither package is part of the main flatbread install, which audits clean. CHANGELOG.md records the details.

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

I added doc comments to any new public exports, and inline comments to any hard-to-understand areas
My changes generate no new console errors locally
If applicable, try to include a test that fails without this PR but passes with it

Does this introduce any non-backwards compatible changes?

Yes
No

The published packages now require Node >=20.19. Runtime APIs do not change.

Does this include any user config changes?

Yes
- If so, I have updated the relevant areas of documentation
No

Move all public packages to 1.0.0, align package metadata, and add the release license.\n\nLead the public docs with Effort Graph agent memory while keeping static relational content and GraphQL read paths clear. Add concise release notes and record the positioning decision in the Effort Graph.\n\nTest plan: pnpm verify; package tarball and clean-install smoke tests. Change-Id: I3b53d7e244cc251ce9968b3578fabeabcc96298f

Drop unused Apollo 3 and GraphQL server packages from the stable package. Update Apollo Server, GraphQL, and lodash-es to supported releases, and keep test-only picomatch out of the published runtime set.\n\nTest plan: pnpm verify; clean tarball install; npm audit and CLI smoke checks. Change-Id: Ib49018eafae4ef88cbbd3975f8149b2102ac1f3f

cursor

Stale comment

Review verdict: REQUEST_CHANGES

Consensus HIGH on invalid bare Effort Graph read CLI names in docs/positioning.md, plus an independent HIGH that published packages still omit LICENSE text from npm tarballs.

Dependency drops/bumps look sound (no remaining imports of removed Apollo 3 / express-graphql / etc.). This is a release/docs/deps PR — no packages/*/src changes — so there is no source coverage plan.

Blocking / high

docs/positioning.md — after `flatbread effort list`, `records` / `relations` / `blocking-decisions` / `get` read as top-level commands; CLI only has flatbread effort <subcommand>.

LICENSE — root MIT text is added, but publishable packages ship files: ["bin","dist",…] with no package LICENSE, so tarballs stay SPDX-only.

Also fix (MED)

Root CHANGELOG says there is no migration guide while engines.node: ">=20.19" breaks Node 18 / early 20.

Effort Graph README overstates journal recovery as always-rollback.

Skill install URL / gitTag: "v1.0.0" will 404 until the annotated tag exists.

effortGraphContent() docs omit the spread/merge pattern when content already has entries.

Coverage plan

none — no source changes.

Perspectives: dependency-runtime-surface, release-discipline, docs-and-positioning, dx-and-examples. Models: grok-4.5 high / composer-2.5.

_{Sent by Cursor Automation: Flatbread PR Review}

cursor · 2026-07-29T11:09:43Z

+source. Writes go through `flatbread effort write`; reads come back as bounded
+digests from `flatbread effort list`, `records`, `relations`,
+`blocking-decisions`, and `get`.


HIGH — These read as top-level commands after `flatbread effort list`. The CLI only registers flatbread effort <subcommand> (effort get, effort records, effort relations, effort blocking-decisions).

Fix: Prefix every read the same way as list, e.g. `flatbread effort records`, `flatbread effort get`.

cursor · 2026-07-29T11:09:43Z

+Writes go through a journal, so a change that touches several files either
+finishes in full or leaves nothing behind: if the process dies mid-write, the
+next run restores the earlier contents of the unfinished change.


MED — “Finishes in full or leaves nothing behind” / “restores the earlier contents” implies always-rollback. Recovery also forward-completes committed-but-unpublished journal transactions.

Fix: Describe both paths — uncommitted → rollback; committed-unpublished → complete on next run.

cursor · 2026-07-29T11:09:43Z

+npx skills add https://github.com/FlatbreadLabs/flatbread/tree/v1.0.0/packages/effort-graph/skills/effort-graph --skill effort-graph
+npm install --save-dev flatbread@1.0.0


MED — Install URL hardcodes tree/v1.0.0 before that annotated tag exists (npm latest is still alpha). The flatbread@1.0.0 line under an @flatbread/effort-graph README can also confuse which package to install.

Fix: Keep the URL generic until publish (or gate tag creation at release), and note that the flatbread meta-package provides the CLI / effortGraphContent re-export.

cursor · 2026-07-29T11:09:43Z

-  "gitTag": "v1.0.0-alpha.22"
+  "flatbreadVersion": "1.0.0",
+  "effortGraphVersion": "1.0.0",
+  "gitTag": "v1.0.0"


MED — Committed gitTag: "v1.0.0" makes skill install paths 404 until the annotated tag is pushed post-publish.

Fix: Treat annotated v1.0.0 tag creation as a hard release checklist gate (already noted in CONTRIBUTING).

cursor · 2026-07-29T11:09:43Z

+For agent memory instead of site content, add `effortGraphContent()` to your
+config, then run `flatbread effort bootstrap` to check the setup and


MED — “Add effortGraphContent() to your config” omits the spread/merge pattern bootstrap emits when content already has entries.

Fix: Show content: [...existing, ...effortGraphContent()] or link packages/effort-graph/skills/effort-graph/setup.md.

Update GraphQL Code Generator and esbuild to supported releases without changing generated output. Trim Proof's npm payload to its bins and built files.\n\nTest plan: pnpm verify; package audits; Proof pack and CLI smoke checks. Change-Id: I69eee15141a4d6332f504bee70f4b533d076e077

Use GraphQL's public types in emitted declarations and declare vfile as a runtime dependency because the public API exposes VFile. Add checks that prevent private GraphQL paths and missing declaration dependencies from returning.\n\nTest plan: pnpm verify; strict clean-consumer TypeScript compile. Change-Id: I3f66f068fa24441f598224f2cfbbec48e722695c

Document the unresolved audit chains in Proof and resolver-svimg. The main Flatbread install remains clean. Change-Id: I4230756307f943c0e72610c25b0c86b625f05ab6

cursor

Review verdict

REQUEST_CHANGES — Core type/dependency packaging for 1.0 looks sound (ExecutionResult / public GraphQL types, vfile as a real dependency, dropped Apollo Express stack clean). Two consensus HIGH doc/release-contract issues are still open before tag: bare Effort CLI names in positioning, and pre-tag v1.0.0 install URLs.

Prior LICENSE packing HIGH is closed for the real publish path: pnpm pack / pnpm publish include root LICENSE even when files omits it (scripts/publish.ts uses pnpm). Engines floor is documented; a short upgrade playbook remains optional.

Blocking / high (fix before tag)

docs/positioning.md — prefix records / relations / blocking-decisions / get with flatbread effort .
packages/effort-graph/README.md — replace hardcoded tree/v1.0.0 and flatbread@1.0.0 with placeholders (or gate after tag).

Also worth fixing

Show content: [...(existing ?? []), ...effortGraphContent()] in packages/flatbread/README.md.
Pin FlatbreadProvider['query'] → Promise<ExecutionResult> (and import ⊆ dependencies) in types.test.ts.
Clarify journal recovery (rollback vs complete; write/start entry points) in the effort-graph README.

Coverage plan

packages/core/src/types.test.ts — positive Equal<ReturnType<FlatbreadProvider['query']>, Promise<ExecutionResult>>.
Same file — every dist/index.d.ts import specifier ⊆ dependencies.
Same file — missing-dist → clear assertion, not raw ENOENT.

Reviewer scoreboard

Perspective	Signal
correctness-and-contracts	strong
test-coverage-robustness	good
release-discipline	mixed (LICENSE HIGH wrong for pnpm)
docs-and-positioning	good
dependency-runtime-surface	strong (APPROVE)

Models: grok-4.5 (HIGH) / composer-2.5 (MED/LOW). Canvas: dag-review-b7164a8-judge.canvas.tsx. Judge: /tmp/review-judge-final.md.

_{Sent by Cursor Automation: Flatbread PR Review}

cursor · 2026-07-29T11:54:02Z

+digests from `flatbread effort list`, `records`, `relations`,
+`blocking-decisions`, and `get`.


HIGH — These read as top-level commands after `flatbread effort list`. records, relations, blocking-decisions, and get are not valid shell invocations on their own.

Prefix each: `flatbread effort records`, `flatbread effort relations`, `flatbread effort blocking-decisions`, `flatbread effort get` (match skill/reference).

cursor · 2026-07-29T11:54:02Z

+npx skills add https://github.com/FlatbreadLabs/flatbread/tree/v1.0.0/packages/effort-graph/skills/effort-graph --skill effort-graph
+npm install --save-dev flatbread@1.0.0


HIGH — Hardcoded tree/v1.0.0 and flatbread@1.0.0 404 until the annotated tag exists. CONTRIBUTING and setup.md correctly use placeholders.

Use <gitTag> / @X (or state “after v1.0.0 is tagged”) so merge-before-tag does not ship broken install lines.

cursor · 2026-07-29T11:54:02Z

+For agent memory instead of site content, add `effortGraphContent()` to your
+config, then run `flatbread effort bootstrap` to check the setup and
+`flatbread effort bootstrap --verify` to fail when something is missing. The
+[Effort Graph README](https://github.com/FlatbreadLabs/flatbread/blob/main/packages/effort-graph/README.md)
+has the install commands.


MED — “Add effortGraphContent() to your config” can be read as replacing content, which wipes posts/authors on dual-use repos.

Show the spread-merge pattern already used in skill setup.md / CLI bootstrap:
content: [...(existing ?? []), ...effortGraphContent()].

cursor · 2026-07-29T11:54:02Z

+Writes go through a journal, so a change that touches several files either
+finishes in full or leaves nothing behind: if the process dies mid-write, the
+next run restores the earlier contents of the unfinished change.


MED — “Finishes in full or leaves nothing behind” / “restores the earlier contents” only covers before-image rollback. recoverJournal also completes committed-but-unpublished transactions via after-images, and recovery runs on write/flatbread start, not read-only CLI.

State both recovery actions and the entry points.

cursor · 2026-07-29T11:54:02Z

+test('core declarations use only the public GraphQL type surface', (t) => {
+  const declarations = readFileSync(
+    new URL('../dist/index.d.ts', import.meta.url),
+    'utf8'
+  );
+
+  t.false(declarations.includes('graphql/jsutils/'));
+});
+
+test('core publishes dependencies used by its declarations', (t) => {
+  const manifest = JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url), 'utf8')
+  ) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+
+  t.is(manifest.dependencies?.vfile, '5.3.4');
+  t.false('vfile' in (manifest.devDependencies ?? {}));


MED — Good negative check (graphql/jsutils/) and vfile pin, but the CHANGELOG’s positive stickiness claim is unlocked: no assert that query returns Promise<ExecutionResult>, and demoting graphql out of dependencies would still pass.

Add Equal<ReturnType<FlatbreadProvider['query']>, Promise<ExecutionResult>> and assert every dist/index.d.ts import specifier ⊆ dependencies.

cursor · 2026-07-29T11:54:02Z

   * @returns GraphQL response
   */
-  async query(args: Omit<GraphQLArgs, 'schema'>) {
+  async query(args: Omit<GraphQLArgs, 'schema'>): Promise<ExecutionResult> {


MED — Public return-type fix is correct; pair it with a compile-time Equal (or d.ts match) in types.test.ts so the private GraphQL type leak cannot regress silently.

cursor · 2026-07-29T11:54:02Z

+There is no migration guide. Of the changes above, the Node floor is the one
+that can break an install. For anything else that moved since
+`1.0.0-alpha.22`, read the Git history; the alpha train did not keep
+per-release notes.


LOW — Engines floor is declared elsewhere; saying there is no migration guide still leaves Node <20.19 upgraders without concrete steps. A short “Upgrading to 1.0” note (nvm/CI/engine-strict) would close the residual gap.

cursoragent added 2 commits July 29, 2026 10:44

cursor Bot reviewed Jul 29, 2026

View reviewed changes

cursoragent added 3 commits July 29, 2026 11:13

docs: record upstream release limits

b7164a8

Document the unresolved audit chains in Proof and resolver-svimg. The main Flatbread install remains clean. Change-Id: I4230756307f943c0e72610c25b0c86b625f05ab6

cursor Bot reviewed Jul 29, 2026

View reviewed changes

		npx skills add https://github.com/FlatbreadLabs/flatbread/tree/v1.0.0/packages/effort-graph/skills/effort-graph --skill effort-graph
		npm install --save-dev flatbread@1.0.0

		For agent memory instead of site content, add `effortGraphContent()` to your
		config, then run `flatbread effort bootstrap` to check the setup and

		digests from `flatbread effort list`, `records`, `relations`,
		`blocking-decisions`, and `get`.

Uh oh!

Uh oh!

Conversation

tonyketcham commented Jul 29, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Verification

Known upstream limits

Please don't delete this checklist! Before submitting the PR, please make sure you do the following:

Does this introduce any non-backwards compatible changes?

Does this include any user config changes?

Uh oh!

cursor Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Review verdict: REQUEST_CHANGES

Blocking / high

Also fix (MED)

Coverage plan

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Review verdict

Blocking / high (fix before tag)

Also worth fixing

Coverage plan

Reviewer scoreboard

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

cursor Bot Jul 29, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tonyketcham commented Jul 29, 2026 •

edited by cursor Bot

Loading

cursor Bot left a comment •

edited

Loading