@flow-as-code/cli 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 The flow-as-code Authors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,446 @@
+# @flow-as-code/cli
+
+Install with `npm i -D @flow-as-code/cli`. Apache-2.0, Node 22.12 or newer.
+Installing it brings the other four, so `npx flow-cli` works straight away. [`examples/promote-across-environments/`](https://github.com/flow-as-code/flow-as-code/tree/main/examples/promote-across-environments)
+is a worked run of `lint` and `emit` against one document and two environments.
+
+<!-- src/cli.test.ts parses the first fenced block below and holds it to what
+     `flow-cli --help` prints, so keep it first and keep it untagged. -->
+
+```
+flow-cli lint <dir-or-file> [--format text|json]        rule set over the whole document set
+flow-cli render <dir-or-file> --resources map.json      standalone materialization
+flow-cli codegen <doc.flowdoc.json> [--out <file.ts>]   FlowDoc -> typed builder TS
+flow-cli synth <file.flow.ts> [--out <dir>]             TS -> FlowDoc (sandboxed child process)
+flow-cli emit <dir> --target cdk|tf [--address-map refs.tfmap.json]
+flow-cli diff <dir> --instance <arn>                     local FlowDocs vs the live instance
+flow-cli export --instance <arn> [--out <dir>] [--no-codegen] [--on-error abort|collect]
+flow-cli simulate <scenarios> --instance <arn> [--resource-map <file>] [--format junit|json] [--out <file>]
+flow-cli studio [dir] [--port <port>]                    local visual editor, live sync both ways
+```
+
+## Availability
+
+Every command above is wired, so `--help` is the complete surface; a test in
+`src/cli.test.ts` holds `--help` and the usage block above to the same list.
+
+| Command    | Status    | Notes                                                                            |
+| ---------- | --------- | -------------------------------------------------------------------------------- |
+| `lint`     | available | Whole set in one pass, so cross-document rules resolve module references         |
+| `codegen`  | available | `@keep` comments in an existing output file survive regeneration                 |
+| `synth`    | available | Sandboxed child process; see below                                               |
+| `render`   | available | Strict resource map; every unmapped token is listed at once                      |
+| `emit`     | available | `--target tf` writes `@flow-as-code/tf` output, `--target cdk` writes a scaffold |
+| `export`   | available | Live instance to FlowDoc pairs; collects failures by default                     |
+| `simulate` | available | Scenario suite through the TestCase API, JUnit or JSON report                    |
+| `diff`     | available | Local documents against the live instance; exit 2 when it cannot tell            |
+| `studio`   | available | Local bridge on 127.0.0.1 serving the studio, with live sync both ways           |
+
+Exit codes: 0 on success, 1 for a failure (a missing path, malformed JSON, a
+schema-invalid document, an unmapped token, an unknown flag value, a lint
+finding with error severity, a flow that could not be exported, a scenario that
+did not pass, or a document that differs from the instance). `diff` alone also
+uses 2, for an error in the comparison itself, so a script can tell "differs"
+from "could not tell".
+
+## Importing it
+
+The command lives in `dist/bin.js` and nothing else loads it, so importing the
+package never parses argv or exits the host process. The package root is a
+library entry, the union of the three subpaths:
+
+```ts
+import { synthFile, createWatcher, startStudioServer } from "@flow-as-code/cli";
+// or, narrower:
+import { synthFile } from "@flow-as-code/cli/synth";
+import { createWatcher } from "@flow-as-code/cli/watch";
+import { startStudioServer } from "@flow-as-code/cli/bridge";
+```
+
+`src/index.test.ts` imports the built root in a child process and fails if it
+writes anything or exits, and holds the root's exports equal to the union of
+the three subpaths.
+
+## Connecting to an instance
+
+`export`, `simulate`, and `diff` take `--instance <arn>`, the instance ARN as
+the console's account overview shows it
+(https://docs.aws.amazon.com/connect/latest/adminguide/find-instance-arn.html).
+Only an instance ARN is accepted: a bare instance id carries no Region, and a
+resource ARN names the wrong thing.
+
+The Region is read from the ARN. Nothing consults `AWS_REGION` or a profile's
+region, so an instance in one Region is never addressed through a client
+configured for another
+(https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-region.html).
+
+Credentials come from the AWS SDK's default provider chain: environment
+variables, the shared config and credentials files with their profiles and SSO
+sessions, web identity, and the container and instance metadata endpoints
+(https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html).
+The CLI takes no credential flags and stores nothing. Pick a profile with
+`AWS_PROFILE` as you would for the AWS CLI.
+
+`@aws-sdk/client-connect` is an optional peer dependency, loaded only when one
+of these three commands runs, so the offline commands do not pay for it. When
+it is not installed the command exits 1 with one line naming the package and
+the install command, no stack trace. An SDK that is installed but will not
+load (a dependency of its own missing, a broken install) is a different
+failure and is reported as `@aws-sdk/client-connect could not be loaded:` with
+the loader's reason, since the install command is not the fix. `simulate` also
+checks that the installed SDK exposes the TestCase operations, which are
+recent, and names the version that has them all when it does not.
+
+Every other command works with no SDK installed and makes no network calls.
+
+## Input and output conventions
+
+`lint`, `render`, and `emit` take a directory or a single file. A directory
+contributes every `*.flowdoc.json` in it, sorted by name, and is not walked
+recursively. Every document is validated against `flowdoc-0.1.schema.json`, the
+byte copy of `conformance/schema/flowdoc-0.1.schema.json` this package ships,
+before any command looks at it, so a malformed document fails with its own path
+named rather than deep inside an emitter.
+
+`--out` defaults to the input directory for every command that writes, and
+`codegen` names its file after the document (`appointment-line.flowdoc.json`
+generates `appointment-line.flow.ts`), which is the inverse of what `synth`
+writes.
+
+## lint
+
+The whole document set goes to `@flow-as-code/core`'s lint in one call. Rules
+receive the other documents alongside their own, and the ones that follow module
+references cannot answer without them: `module-depth-5` on a single file reports
+nothing, correctly, because depth is not computable from one document.
+
+`--format json` prints the stable machine-readable report (a `summary` plus
+`findings`) on stdout; the failure line goes to stderr, so the JSON stays clean
+for a pipe. Exit status follows severity, not count: any `error` exits 1,
+warnings alone exit 0.
+
+Every document is schema-checked before any rule runs, so a document the schema
+rejects never reaches the report. A literal ARN is the one violation that is
+both a schema failure and a named rule, and the schema states it four ways per
+field without ever saying "literal ARN", so it is reported once per offending
+field as `no-literal-arn: "<field>" contains a literal ARN`. Schema errors the
+ARN did not cause are still listed.
+
+## render
+
+Materializes each document with `materializeWithMap` and writes
+`<doc name>.json`. This is the one path where a literal ARN is the goal rather
+than a mistake, so map values are not linted. Completeness is enforced: a token
+with no entry in the map is fatal, and every missing token across every document
+is printed in one run.
+
+## emit
+
+`--target tf` is a thin wrapper over `@flow-as-code/tf`, writing exactly
+the bytes the emitter returns and nothing of its own. `--address-map` is passed
+through as `options.addressMap`; without one, unresolved references become the
+emitter's loud `TODO_MISSING_ADDRESS_*` placeholders, which fail
+`terraform validate` rather than deploying a broken flow.
+
+`--target cdk` is not a code generator, because `@flow-as-code/cdk` is a
+library: `FlowSet` reads the FlowDoc directory itself at synth time. What the
+command writes is `flow-stack.ts`, a compiling scaffold that constructs a
+`FlowSet` over the directory and declares a `TokenBinder` carrying one `TODO`
+per reference type the documents actually use, with the referenced names listed.
+Reference types the set does not use still get a method, because `TokenBinder`
+requires them, but theirs throws instead of carrying a TODO. Module references
+never appear: `FlowSet` resolves those itself against the modules it manages.
+Re-running the command overwrites the file, so move or rename it once you have
+filled it in.
+
+The generator lives in `@flow-as-code/cdk/scaffold`, not here, because the
+studio's CDK export button has to produce the same bytes and cannot import this
+package (`@flow-as-code/cli` depends on `@flow-as-code/studio` for its built
+assets). What stays here is the path arithmetic: turning `--out` and the
+documents' directory into the relative `FLOW_DOCS` expression. The scaffold
+resolves that expression against its own file (`new URL(..., import.meta.url)`),
+so `cdk synth` works from the project root, where `cdk.json` normally lives, and
+not only from the directory the scaffold was written to.
+
+## synth
+
+`flow-cli synth <file.flow.ts> [--out <dir>]` evaluates a TypeScript builder
+file and writes one `<flow.name>.flowdoc.json` per flow it exports, into
+`--out` or, by default, next to the source file. A flow is any exported `Flow`
+instance and the result of any exported zero-argument function that returns one.
+Output is byte-stable (`@flow-as-code/core`'s canonical serializer) and carries
+`meta.generator` (`cli@<version>`) and `meta.sourceHash` (`sha256:<hex>` of the
+source file bytes).
+
+A builder file does not need `@flow-as-code/core` installed beside it. The child
+resolves that import normally first, so a copy in the file's own `node_modules`
+wins; only when nothing resolves does it fall back to the copy flow-cli itself
+is running against. That is what lets a folder holding nothing but FlowDocs and
+the `.flow.ts` files `codegen` wrote next to them synth at all. The fallback
+covers `@flow-as-code/core` and nothing else, so a builder file cannot reach the
+rest of `@flow-as-code/cli`'s dependencies through it. A `.flow.ts` is also
+treated as ESM when no `package.json` above it says otherwise, which is what
+codegen emits and the only form that can import `@flow-as-code/core`.
+
+The builder file never runs in the CLI process. It runs in a child node with
+tsx registered via `--import`, a stripped environment (PATH plus a private
+temp dir for tsx), and cwd pinned to the source directory. Where the runtime
+has the stable `--permission` flag (Node 22.13+), Node's permission model is
+enabled: file writes are denied everywhere except tsx's private temp dir (the
+parent process writes the FlowDocs), and child processes are denied. File
+reads are not jailed, and on Node 22/24 the permission model does not cover
+network access at all; see the header comment in `src/synth.ts` for exactly
+what is and is not enforced, with citations.
+
+## diff
+
+`flow-cli diff <dir> --instance <arn>` answers whether what is checked in
+matches what is deployed. Every `*.flowdoc.json` in `<dir>` is validated and
+paired with the live flow or module of the same kind and name, where the live
+name is the slug `export` derives from the console name. The live side goes
+through the same exporter, so it carries tokens rather than ARNs, and the two
+documents are compared as canonical JSON with `layout` and `meta` removed:
+positions and provenance are not differences anyone deploys.
+
+One line per local document, in path order, then a unified diff of the
+canonical JSON under each changed one:
+
+```
+flows/appointment-line.flowdoc.json: changed
+--- local/flows/appointment-line.flowdoc.json
++++ live/appointment-line
+@@ -13,7 +13,7 @@
+...
+flows/recording-consent.flowdoc.json: unchanged
+flows/callback-offer.flowdoc.json: missing-live
+```
+
+Live flows with no local document are not reported. The same two states
+always print the same bytes, so the output can be compared across runs.
+
+A live flow that has never been published has no published content, so the
+exporter reads its saved content through the `$SAVED` alias, the same way
+`export` does. The line says so, `flows/draft-line.flowdoc.json: unchanged
+($SAVED)`, and a diff under it is labelled `+++ live/draft-line:$SAVED`.
+Unchanged against a draft means the draft matches, not that anything is
+deployed.
+
+Exit 0 when nothing differs, 1 when any document is changed or has no live
+counterpart, and 2 when the comparison itself failed: bad arguments (a missing
+`--instance` or an unknown flag included, where every other command exits 1),
+the SDK not installed, the instance unreadable, or a matched live flow the
+exporter could not convert (that document prints as `error:` with the reason,
+and the run still reports the rest).
+
+## export
+
+`flow-cli export --instance <arn> [--out <dir>] [--no-codegen] [--on-error abort|collect]`
+reads every flow and module in the instance and writes `<name>.flowdoc.json`
+plus `<name>.flow.ts` for each into `--out`, which defaults to the working
+directory and is created if needed. `--no-codegen` writes the documents only.
+References come out as tokens, never ARNs, and the name is the slug the
+exporter derives from the console name (`Appointment Line` becomes
+`appointment-line`). A flow and a module that slug to the same name would
+share a file name; the second one is reported as a failure rather than
+overwriting the first.
+
+Each pair is written the way `synth` and the studio write it: the document
+carries `meta.sourceHash` of the generated source, so the watch engine sees an
+exported pair as in sync, and an existing `<name>.flow.ts` is read first so
+its `@keep` comments survive, as with `codegen`. A flow that has never been
+published is read through the documented `$SAVED` alias and marked as such in
+the summary.
+
+stdout carries one line per document written and a closing count; stderr
+carries the exporter's warnings (`warning: ...`, for content it had to skip or
+could not fully represent) and one `failed: <name> (<arn>): <reason>` line per
+flow it could not export.
+
+```
+appointment-line (flow): appointment-line.flowdoc.json, appointment-line.flow.ts
+recording-consent (module): recording-consent.flowdoc.json, recording-consent.flow.ts
+Exported 2 of 3 to /work/flows
+```
+
+`--on-error` defaults to `collect`, which writes everything that exported and
+reports every failure at once. `abort` stops at the first failure and writes
+nothing. The default is collect because a fresh instance always holds the
+stock "Sample Lambda integration" flow, which calls a Lambda in an AWS-owned
+account that the instance's Lambda list cannot return; that is an unknown-ARN
+hard error by design (see the Export section of `packages/core/SPEC.md`),
+and aborting on it would make a first export of any new instance write
+nothing. Either mode exits 1 when any flow failed.
+
+`--on-error` governs flows only. The inventory listing that precedes them
+(flows, modules, queues, hours, prompts, Lambda functions, bots) fails in
+either mode with the SDK's own message, an `AccessDeniedException` naming the
+missing action for instance, and nothing is written.
+
+## simulate
+
+`flow-cli simulate <scenarios> --instance <arn> [--resource-map <file>] [--format junit|json] [--out <file>]`
+runs a scenario suite through the instance's TestCase operations
+(https://docs.aws.amazon.com/connect/latest/adminguide/testing-simulation-execute-test-cases.html)
+within the documented limits, 5 concurrent, 100 in flight, 5 minutes per
+scenario, and writes a report.
+
+`<scenarios>` is one scenario file, or a directory. A directory contributes
+every `scenario.json` and `*.scenario.json` directly in it and one level down,
+which is the layout of `conformance/simulate/` (one `scenario.json` per case
+directory); other files are ignored.
+
+Everything that can fail offline fails before the instance is touched, and
+all at once. Every scenario is validated against `scenario-0.1.schema.json`,
+the byte copy of `conformance/schema/scenario-0.1.schema.json` this package
+ships, then against the cross-field rules the schema cannot express, and every
+`${cdref:...}` token in the suite is resolved through `--resource-map`, a JSON
+object from token to ARN in the same shape `render` takes. A suite with one
+broken scenario or one unmapped token creates no test case.
+
+The report goes to stdout, or to `--out`, in which case the path is printed
+instead. `--format junit` (the default) is the `<testsuites>` document CI
+systems ingest; `--format json` is the stable `flow-simulate-report/0.1`
+document. Scenarios that did not pass are also described on stderr, one block
+per scenario with the failed observations, so a CI log says why without
+opening the report.
+
+Exit 0 only when every scenario `PASSED`. `FAILED`, `TIMED_OUT` (the harness
+stops the execution when the 5 minutes are up), `STOPPED`, and `ERRORED` (an
+API error for that scenario) each exit 1, and the summary line says how many
+of the suite did not pass.
+
+## watch (library)
+
+`@flow-as-code/cli/watch` exports `createWatcher(dir)`, the engine
+behind studio sync (A11). It watches one directory (non-recursive) and pairs
+`<name>.flow.ts` with `<name>.flowdoc.json` by base name. On a ts change it
+re-synths in the same sandboxed child and rewrites the doc, guarded by
+`meta.sourceHash` (docs/01-flowdoc-spec.md, invariant 3): if the doc on disk
+was edited externally since the watcher last wrote or observed it, and that
+edit does not carry the previous ts content's hash, the pair is dirty on both
+sides. The watcher then emits `conflict` and writes nothing. A pair that is
+already diverged when the watcher starts also gets a `conflict` rather than
+an overwrite.
+
+The re-synth uses the same resolution rules `synth` documents above, so a
+watched directory needs no `node_modules` of its own for the builder files in
+it to resolve `@flow-as-code/core`.
+
+Events: `synced {tsPath, docPath, name}`, `conflict {tsPath, docPath, name,
+reason}`, `error {path, message}`, plus a `ready` convenience event after the
+initial scan settles. A ts file whose flow names do not include the file's
+base name syncs only when it exports exactly one flow; otherwise the watcher
+emits `error` for that pair.
+
+A change that leaves the builder file byte-identical to the last synced content
+is normally silent (it is how the watcher recognizes its own writes), with one
+exception: when the preceding change ended in `error`, the same no-op emits
+`synced`. Undoing a broken edit is the ordinary way to fix one, and consumers
+latch the error, so without that event the studio's out-of-sync badge outlived
+the state it reported and cleared only on some later, unrelated edit.
+
+`noteWrite(name, {tsContent, docContent})` records a pair another part of the
+same process just wrote as the clean baseline, so the studio bridge's own
+writes are not read back as external edits. Pass the exact bytes written, and
+call it after both files are on disk.
+
+## studio
+
+`flow-cli studio [dir] [--port <port>]` serves the visual editor over a
+directory of FlowDocs and builder files, with live sync in both directions. It
+prints the URL to open; `dir` defaults to the working directory and the port
+defaults to a free one.
+
+A document with no `<name>.flow.ts` beside it gets one written before the
+server starts, and the command prints a line per file:
+
+```
+wrote    appointment-line.flow.ts from appointment-line.flowdoc.json
+```
+
+That is the same `codegen` the canvas runs on save, so the bytes are the ones
+the first save would have written, and the document is stamped with the
+`meta.sourceHash` of the source just generated. Without it a directory holding
+only documents (exported from an instance, copied out of `conformance/`, sent
+by a colleague) had no builder file to edit, so the loop this command exists
+for could not start there. An existing builder file is never overwritten. A
+document `codegen` refuses is named and skipped, and the rest of the directory
+still opens:
+
+```
+skipped  broken.flowdoc.json: broken.flowdoc.json is not a valid FlowDoc: ...
+```
+
+A builder file the watcher cannot synth is reported on the same stream:
+
+```
+error    appointment-line.flow.ts: Evaluating /w/appointment-line.flow.ts threw: Transform failed with 1 error:
+/w/appointment-line.flow.ts:101:16: ERROR: Unexpected ";"
+```
+
+Stack frames inside `node_modules` and node's own internals are dropped from
+that message. A transform failure carries ten frames of esbuild and stream
+internals under a line that already names the file, line and column, and the
+studio's badge shows only the first line for the same reason. Frames in files
+you wrote survive, because a runtime throw inside a flow needs them. There is
+no switch that restores the dropped frames. `node_modules` has to be a whole
+path segment of the frame's own location for the frame to count as vendor code,
+so a project under a directory called `node_modules-sandbox`, or a function
+named `loadNodeModules`, keeps its frames.
+
+A pair assembled by hand is a different case and still reports a conflict: the
+document has to carry the `meta.sourceHash` of the source next to it, or the
+watcher has no evidence the two ever agreed. `flow-cli synth <name>.flow.ts`
+writes that stamp; removing the stale side works too.
+
+The server binds `127.0.0.1` and only `127.0.0.1`. This process writes files
+you own, so a bridge reachable from the network would be a remote file writer;
+the bind address is not configurable for that reason. Binding loopback is not
+by itself protection against DNS rebinding (a page on the internet can resolve
+its own hostname to 127.0.0.1), so the `Host` header is checked as well and a
+request addressed to anything else is refused. No CORS headers are sent, and
+the server makes no outbound connections.
+
+What it serves: the built studio assets from the installed
+`@flow-as-code/studio` package, and a small JSON API under `/bridge`.
+If the studio package is present but has not been built, the command says so
+and names the build command.
+
+The API is these six routes and nothing else; anything else under `/bridge`
+answers 404 with the method and path it was given
+(`src/bridge/server.ts`):
+
+| Route                         | Method | What it does                                         |
+| ----------------------------- | ------ | ---------------------------------------------------- |
+| `/bridge/info`                | GET    | Served directory, version, and the session token     |
+| `/bridge/docs`                | GET    | Names of the documents in the served directory       |
+| `/bridge/docs/<name>`         | GET    | One pair: the FlowDoc and its `<name>.flow.ts`       |
+| `/bridge/docs/<name>`         | PUT    | Save that pair; 409 when the pair diverged           |
+| `/bridge/docs/<name>/resolve` | POST   | Settle a refused save by choosing a side             |
+| `/bridge/export`              | POST   | Write an emitted file map under the served directory |
+| `/bridge/events?cursor=<n>`   | GET    | Long-polled watch events from `<n>` on               |
+
+Every request to `/bridge` and to the document itself carries the session
+token, either as the `token` query parameter (which is how the printed URL
+opens the page) or as the `x-flow-studio-token` header (which is how the page's
+own calls send it). Subresources are served without one so the token never
+appears in an asset URL. `src/bridge/forgery.test.ts` holds this contract,
+along with the `Sec-Fetch-Site` and `Origin` checks described above.
+
+`POST /bridge/export` is how the studio's export buttons reach disk: the studio
+emits the file map (the same emitters this CLI's `emit` and `render` use) and
+this process writes it under the served directory. Paths are checked against
+the protocol's path rule and then again by resolving them and requiring the
+result to be inside that directory. Nothing is paired and no event is
+published: emitted terraform and CDK files are output, not documents.
+
+Saving from the canvas writes both halves of the pair: the FlowDoc, and
+`<name>.flow.ts` regenerated with `codegen`, passing the existing file so
+`@keep` comments survive. The document is stamped with `meta.sourceHash` of
+the source just written, which is what keeps the watcher from reading the
+save as a divergence.
+
+Conflicts are never merged. A save whose builder file has changed since the
+document was generated from it is refused with 409 and both sides are offered
+in the studio's dialog; so is a pair the watcher finds diverged on disk. Every
+write stays refused until the choice is made.