@jawache/flow 0.1.0

package/dist/types/packs/typescript.d.ts

@@ -0,0 +1,101 @@
+/** What this pack cannot know: the two gate recipes, and whether the repo has shared config files. */
+export interface Gates {
+    /** The recipe that typechecks every project in one pass. */
+    readonly typecheck: string;
+    /** The recipe that lints the repo. */
+    readonly lint: string;
+    /**
+     * The shared tsconfig every project must extend — a path (`./tsconfig.base.json`) or a package
+     * name. Optional, and with nothing here the rule does not ask for one.
+     *
+     * flow ships no such file: a base states one fleet's opinion about target, module and lib, and a
+     * neutral engine has no business having one. What the pack holds without it is the opinion that
+     * travels — `strictOptions` below stay on wherever they are set.
+     */
+    readonly tsconfigBase?: string;
+    /**
+     * The shared eslint config the repo's own config must import — a path
+     * (`./eslint.config.base.js`) or a package name. Optional; with nothing here there is no entry.
+     */
+    readonly eslintBase?: string;
+    /**
+     * The compiler options that may never be turned off. Defaults to `["strict",
+     * "noUncheckedIndexedAccess"]`.
+     *
+     * Stated as option names under `compilerOptions`, each asserted `true`. This is the pack's whole
+     * opinion when no base file is named.
+     */
+    readonly strictOptions?: readonly string[];
+}
+/**
+ * TypeScript discipline as shared configuration: strict stays on, the checker is never silenced.
+ *
+ * This pack does not re-implement a linter. The escape hatches — `@ts-expect-error`, explicit
+ * `any`, double assertions — are typescript-eslint's `strictTypeChecked` job, and it does it
+ * better than a hand-rolled pattern can. What is left is the half a linter cannot do: keep the
+ * repo's own configs pointing at a shared base, run both tools at the gate, and teach the design
+ * habit no tool checks.
+ *
+ * @setup The two gate recipes, and nothing else. THIS PACK SHIPS NO FILE: a base states one
+ * fleet's opinion about target, module and lib, and a neutral engine has no business having one,
+ * so with no base named the pack holds only the opinion that travels — the strict options stay on
+ * wherever they are set.
+ *
+ * A shared base is still worth having, and a repo that keeps one names it in `tsconfigBase` and
+ * `eslintBase`; the two rules then hold every project to it. REFERENCE below, not a file to match:
+ * the smallest base that carries the opinion, to copy as `tsconfig.base.json` and then add a
+ * repo's own emit and module settings to. Every `tsconfig*.json` extends it.
+ *
+ * ```json
+ * {
+ *   "compilerOptions": {
+ *     "strict": true,
+ *     "noUncheckedIndexedAccess": true,
+ *     "exactOptionalPropertyTypes": true,
+ *     "noImplicitOverride": true,
+ *     "noFallthroughCasesInSwitch": true,
+ *     "noUnusedLocals": true,
+ *     "noUnusedParameters": true
+ *   }
+ * }
+ * ```
+ *
+ * …and the lint half as `eslint.config.base.js`, which the repo's own `eslint.config.js` imports
+ * and spreads. It is deliberately not a hand-rolled rule set: `strictTypeChecked` is the maintained
+ * good-patterns set, it already holds the escape hatches at error, and it supersedes every idiom
+ * rule a pack could write. `projectService` is what makes the type-aware rules work at all.
+ *
+ * ```js
+ * import tseslint from "typescript-eslint";
+ *
+ * export default tseslint.config(
+ *   { ignores: ["dist/**", "coverage/**"] },
+ *   ...tseslint.configs.strictTypeChecked,
+ *   {
+ *     languageOptions: {
+ *       parserOptions: { projectService: true, tsconfigRootDir: import.meta.dirname },
+ *     },
+ *   },
+ * );
+ * ```
+ * @adopt Bind it with the two gate recipes this repo really has. Expect the first commit after
+ * binding to run both tools over everything — a repo that has been typechecking one project at a
+ * time usually finds errors in the ones nobody was checking.
+ */
+export declare const typescript: import("../index.ts").Pack<{
+    commitRunsTsc: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "commit">;
+    commitRunsEslint: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "commit">;
+    eslintFromBase?: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+    /**
+     * Without it, strictness is treated as a setting rather than a design tool: the escape hatches
+     * get reached for under time pressure, and impossible states go on being representable because
+     * nothing ever said to model them out.
+     */
+    strictTypesNoInvalidStates: import("../index.ts").BreadcrumbSentence<"text" | "at" | "on" | "description", "touch">;
+    /**
+     * Without it, a project quietly stops extending the shared base — or extends it and then turns
+     * `strict` back off — and the fleet's one standard becomes per-project taste that only shows up
+     * as a bug much later.
+     */
+    tsconfigStrict: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "on" | "description", "write" | "commit">;
+}, Gates>;

package/dist/types/packs/work.d.ts

@@ -0,0 +1,49 @@
+/** The top-level chat: no sidecar, no agent type. The supervisor's rung. */
+export declare const parent: import("../index.ts").Category;
+/**
+ * A supervised builder — one phase of a plan, its own to write.
+ *
+ * The two brief needles are the two sentences a builder's own brief always carries, and they
+ * recover every builder the generic buckets hid.
+ */
+export declare const builder: import("../index.ts").Category;
+/**
+ * Anything spawned to JUDGE rather than to build — the verifier at a phase boundary, and the five
+ * review lenses a closing review spawns.
+ *
+ * One category rather than six, because the rules that bind to it say the same thing to all of
+ * them: a reader does not write. The verifier's own agent definition withholds Edit and Write
+ * already; this is the half that holds for the lenses too, and it holds at the rail rather than in
+ * a frontmatter list somebody can widen.
+ */
+export declare const checker: import("../index.ts").Category;
+/**
+ * The WORK LIFECYCLE's rungs: who is acting, and what each rung may do.
+ *
+ * A pack for repos that run the `work` lifecycle skill — spec · plan · start · build · review ·
+ * reflect · complete. It names the three rungs the lifecycle has (parent · builder · checker),
+ * binds one rule per rung to keep them from doing each other's jobs, and adds the two rules about
+ * the commands that write the journal: the inbox is the human's queue, and prose recorded through
+ * a shell is prose the shell can rewrite first.
+ *
+ * IT IMPORTS NOTHING FROM WORK. It is a plain consumer of flow's public door, exactly like every
+ * other pack here, and it knows the work CLI only as command strings on a rail. That is what lets
+ * flow ship it without depending on the tool it is about.
+ *
+ * flow ships no category names and never will: what a rung is called is a property of the way a
+ * team works, not of a guard engine. These three are the WORK lifecycle's, defined here beside the
+ * rules that bind to them — a builder may not do a parent's job, a checker may not write.
+ *
+ * @install The `work` CLI and its lifecycle skill. Every rule here reads a `work …` command line,
+ * so in a repo that does not run the lifecycle they are five rules that can never fire.
+ * @adopt Bind it only in a repo whose tasks are actually run through the lifecycle. The three rung
+ * rules are scoped to categories this pack defines, so they judge nobody until a session is
+ * classified as a builder or a checker — a human at a keyboard is neither.
+ */
+export declare const work: import("../index.ts").Pack<{
+    planIsTheParents: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "command">;
+    checkersDoNotWrite: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "write">;
+    ticksAreTheChilds: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "for" | "description", "command">;
+    noAgentInboxItems: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+    noShellSubstitutionInProse: import("../index.ts").GuardrailSentence<"at" | "check" | "message" | "test" | "description", "command">;
+}, undefined>;

package/dist/types/version.d.ts

@@ -0,0 +1,2 @@
+/** The version of the `flow` build that is running. `0.0.0-dev` when run from source. */
+export declare const VERSION: string;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@jawache/flow",
+  "version": "0.1.0",
+  "description": "Guardrails and breadcrumbs as code — packs you import, a config that typechecks, one adapter per harness.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jawache/flow.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "guardrails",
+    "hooks",
+    "lint"
+  ],
+  "type": "module",
+  "bin": {
+    "flow": "dist/flow.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./packs": {
+      "types": "./dist/types/packs/index.d.ts",
+      "default": "./dist/packs.mjs"
+    }
+  },
+  "files": [
+    "dist/flow.mjs",
+    "dist/index.mjs",
+    "dist/packs.mjs",
+    "dist/types/"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "//": "Commands live in the justfile — run `just` (build · typecheck · test · test-rules · test-packs · gate · link · release)."
+  },
+  "dependencies": {
+    "@ast-grep/napi": "^0.42.3",
+    "dependency-cruiser": "^18.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.13.4",
+    "@vitest/coverage-v8": "4.1.10",
+    "commit-and-tag-version": "^13.1.2",
+    "esbuild": "^0.28.1",
+    "eslint": "^10.8.1",
+    "eslint-plugin-n": "^18.3.0",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "4.1.10"
+  }
+}