@granular-software/fractory 0.0.0-stage → 0.1.25
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +4 -0
- package/README.md +28 -2
- package/dist/activity-volume.d.ts +18 -0
- package/dist/activity-volume.js +94 -0
- package/dist/annotations.d.ts +122 -0
- package/dist/annotations.js +304 -0
- package/dist/benchmark-cli.d.ts +1 -0
- package/dist/benchmark-cli.js +95 -0
- package/dist/benchmark-worker.d.ts +2 -0
- package/dist/benchmark-worker.js +22 -0
- package/dist/benchmarks.d.ts +19 -0
- package/dist/benchmarks.js +414 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +63 -0
- package/dist/block-cli.d.ts +1 -0
- package/dist/block-cli.js +88 -0
- package/dist/block-documents.d.ts +35 -0
- package/dist/block-documents.js +84 -0
- package/dist/change-impact.d.ts +55 -0
- package/dist/change-impact.js +223 -0
- package/dist/check-source.d.ts +2 -0
- package/dist/check-source.js +66 -0
- package/dist/checks-model.d.ts +64 -0
- package/dist/checks-model.js +36 -0
- package/dist/cli.d.ts +2 -0
- package/dist/cli.js +359 -0
- package/dist/code-model.d.ts +38 -0
- package/dist/code-model.js +94 -0
- package/dist/code-store.d.ts +9 -0
- package/dist/code-store.js +79 -0
- package/dist/compare-artifact.d.ts +6 -0
- package/dist/compare-artifact.js +277 -0
- package/dist/compare.d.ts +81 -0
- package/dist/compare.js +291 -0
- package/dist/compiler.d.ts +10 -0
- package/dist/compiler.js +1240 -0
- package/dist/compose.d.ts +9 -0
- package/dist/compose.js +72 -0
- package/dist/core.d.ts +87 -0
- package/dist/core.js +207 -0
- package/dist/coverage-cli.d.ts +1 -0
- package/dist/coverage-cli.js +42 -0
- package/dist/declaration-sources.d.ts +3 -0
- package/dist/declaration-sources.js +51 -0
- package/dist/declared-graph.d.ts +3 -0
- package/dist/declared-graph.js +67 -0
- package/dist/display-name.d.ts +2 -0
- package/dist/display-name.js +8 -0
- package/dist/error-heat.d.ts +58 -0
- package/dist/error-heat.js +96 -0
- package/dist/evidence.d.ts +3 -0
- package/dist/evidence.js +68 -0
- package/dist/factory-graph.d.ts +7 -0
- package/dist/factory-graph.js +389 -0
- package/dist/factory-model.d.ts +111 -0
- package/dist/factory-model.js +1 -0
- package/dist/git-code.d.ts +47 -0
- package/dist/git-code.js +352 -0
- package/dist/git-refs.d.ts +4 -0
- package/dist/git-refs.js +37 -0
- package/dist/history-activity.d.ts +4 -0
- package/dist/history-activity.js +129 -0
- package/dist/history-churn.d.ts +36 -0
- package/dist/history-churn.js +302 -0
- package/dist/history-git.d.ts +21 -0
- package/dist/history-git.js +125 -0
- package/dist/history-ledger.d.ts +43 -0
- package/dist/history-ledger.js +450 -0
- package/dist/history-ownership.d.ts +10 -0
- package/dist/history-ownership.js +75 -0
- package/dist/history-source.d.ts +13 -0
- package/dist/history-source.js +100 -0
- package/dist/integrations-cli.d.ts +2 -0
- package/dist/integrations-cli.js +159 -0
- package/dist/interface-map.d.ts +15 -0
- package/dist/interface-map.js +125 -0
- package/dist/issue-cache.d.ts +9 -0
- package/dist/issue-cache.js +68 -0
- package/dist/issue-cli.d.ts +1 -0
- package/dist/issue-cli.js +89 -0
- package/dist/issue-links.d.ts +15 -0
- package/dist/issue-links.js +125 -0
- package/dist/linear-issues.d.ts +19 -0
- package/dist/linear-issues.js +124 -0
- package/dist/local-runtime.d.ts +8 -0
- package/dist/local-runtime.js +59 -0
- package/dist/map-activity.d.ts +73 -0
- package/dist/map-activity.js +234 -0
- package/dist/map-model.d.ts +5 -0
- package/dist/map-model.js +166 -0
- package/dist/map-quality.d.ts +20 -0
- package/dist/map-quality.js +61 -0
- package/dist/mapping-coverage.d.ts +87 -0
- package/dist/mapping-coverage.js +404 -0
- package/dist/model.d.ts +186 -0
- package/dist/model.js +66 -0
- package/dist/operation-benchmark-worker.d.ts +2 -0
- package/dist/operation-benchmark-worker.js +60 -0
- package/dist/operation-benchmark.d.ts +29 -0
- package/dist/operation-benchmark.js +1 -0
- package/dist/otel-metrics.d.ts +21 -0
- package/dist/otel-metrics.js +146 -0
- package/dist/performance-model.d.ts +185 -0
- package/dist/performance-model.js +396 -0
- package/dist/product-map.d.ts +71 -0
- package/dist/product-map.js +197 -0
- package/dist/provider-access.cjs +207 -0
- package/dist/provider-access.d.cts +14 -0
- package/dist/public-boundaries.d.ts +13 -0
- package/dist/public-boundaries.js +115 -0
- package/dist/reports-cli.d.ts +1 -0
- package/dist/reports-cli.js +111 -0
- package/dist/reports-model.d.ts +27 -0
- package/dist/reports-model.js +39 -0
- package/dist/reports.d.ts +23 -0
- package/dist/reports.js +223 -0
- package/dist/repository-map.d.ts +22 -0
- package/dist/repository-map.js +153 -0
- package/dist/resource-cache.d.ts +17 -0
- package/dist/resource-cache.js +65 -0
- package/dist/review-cli.d.ts +19 -0
- package/dist/review-cli.js +224 -0
- package/dist/review.d.ts +48 -0
- package/dist/review.js +289 -0
- package/dist/runtime-metrics.d.ts +26 -0
- package/dist/runtime-metrics.js +290 -0
- package/dist/scope.d.ts +14 -0
- package/dist/scope.js +168 -0
- package/dist/sentry-activity.d.ts +39 -0
- package/dist/sentry-activity.js +174 -0
- package/dist/sentry.d.ts +130 -0
- package/dist/sentry.js +369 -0
- package/dist/service-release.d.ts +16 -0
- package/dist/service-release.js +14 -0
- package/dist/setup-cli.d.ts +2 -0
- package/dist/setup-cli.js +52 -0
- package/dist/setup-kit.cjs +163 -0
- package/dist/setup-kit.d.cts +32 -0
- package/dist/source-index.d.ts +37 -0
- package/dist/source-index.js +170 -0
- package/dist/source-review-git.d.ts +7 -0
- package/dist/source-review-git.js +105 -0
- package/dist/source-review.d.ts +18 -0
- package/dist/source-review.js +573 -0
- package/dist/telemetry.d.ts +17 -0
- package/dist/telemetry.js +51 -0
- package/dist/time-window.d.ts +9 -0
- package/dist/time-window.js +35 -0
- package/dist/trace-evidence.d.ts +23 -0
- package/dist/trace-evidence.js +55 -0
- package/dist/trace-model.d.ts +26 -0
- package/dist/trace-model.js +1 -0
- package/dist/tracing.d.ts +44 -0
- package/dist/tracing.js +123 -0
- package/dist/work-check.d.ts +18 -0
- package/dist/work-check.js +115 -0
- package/dist/work-cli.d.ts +1 -0
- package/dist/work-cli.js +176 -0
- package/dist/work-context.d.ts +59 -0
- package/dist/work-context.js +594 -0
- package/dist/work-intents.d.ts +6 -0
- package/dist/work-intents.js +140 -0
- package/dist/work-items.d.ts +58 -0
- package/dist/work-items.js +86 -0
- package/dist/work-lock-check.d.ts +12 -0
- package/dist/work-lock-check.js +339 -0
- package/dist/work-locks.d.ts +10 -0
- package/dist/work-locks.js +98 -0
- package/dist/work-model.d.ts +119 -0
- package/dist/work-model.js +310 -0
- package/dist/work-review-git.d.ts +8 -0
- package/dist/work-review-git.js +111 -0
- package/dist/work-review.d.ts +26 -0
- package/dist/work-review.js +426 -0
- package/dist/work-switcher-model.d.ts +43 -0
- package/dist/work-switcher-model.js +79 -0
- package/dist/work-switcher.d.ts +6 -0
- package/dist/work-switcher.js +171 -0
- package/dist/working-cli.d.ts +1 -0
- package/dist/working-cli.js +33 -0
- package/dist/working-code.d.ts +74 -0
- package/dist/working-code.js +421 -0
- package/dist/workspace-notes.d.ts +71 -0
- package/dist/workspace-notes.js +177 -0
- package/dist/workspace-tests.d.ts +21 -0
- package/dist/workspace-tests.js +573 -0
- package/package.json +547 -4
- package/src/activity-volume.ts +149 -0
- package/src/annotations.ts +485 -0
- package/src/benchmark-cli.ts +118 -0
- package/src/benchmark-worker.ts +22 -0
- package/src/benchmarks.ts +493 -0
- package/src/bin.ts +54 -0
- package/src/block-cli.ts +106 -0
- package/src/block-documents.ts +117 -0
- package/src/change-impact.ts +280 -0
- package/src/check-source.ts +82 -0
- package/src/checks-model.ts +108 -0
- package/src/cli.ts +440 -0
- package/src/code-model.ts +159 -0
- package/src/code-store.ts +98 -0
- package/src/compare-artifact.ts +314 -0
- package/src/compare.ts +440 -0
- package/src/compiler.ts +1512 -0
- package/src/compose.ts +94 -0
- package/src/core.ts +361 -0
- package/src/coverage-cli.ts +52 -0
- package/src/declaration-sources.ts +69 -0
- package/src/declared-graph.ts +75 -0
- package/src/display-name.ts +8 -0
- package/src/error-heat.ts +161 -0
- package/src/evidence.ts +94 -0
- package/src/factory-graph.ts +462 -0
- package/src/factory-model.ts +82 -0
- package/src/git-code.ts +461 -0
- package/src/git-refs.ts +43 -0
- package/src/history-activity.ts +146 -0
- package/src/history-churn.ts +416 -0
- package/src/history-git.ts +163 -0
- package/src/history-ledger.ts +636 -0
- package/src/history-ownership.ts +116 -0
- package/src/history-source.ts +117 -0
- package/src/integrations-cli.ts +187 -0
- package/src/interface-map.ts +166 -0
- package/src/issue-cache.ts +96 -0
- package/src/issue-cli.ts +137 -0
- package/src/issue-links.ts +153 -0
- package/src/linear-issues.ts +154 -0
- package/src/local-runtime.ts +70 -0
- package/src/map-activity.ts +309 -0
- package/src/map-model.ts +213 -0
- package/src/map-quality.ts +66 -0
- package/src/mapping-coverage.ts +570 -0
- package/src/model.ts +228 -0
- package/src/operation-benchmark-worker.ts +60 -0
- package/src/operation-benchmark.ts +28 -0
- package/src/otel-metrics.ts +176 -0
- package/src/performance-model.ts +575 -0
- package/src/product-map.ts +271 -0
- package/src/provider-access.cjs +207 -0
- package/src/provider-access.d.cts +14 -0
- package/src/public-boundaries.ts +143 -0
- package/src/reports-cli.ts +125 -0
- package/src/reports-model.ts +73 -0
- package/src/reports.ts +276 -0
- package/src/repository-map.ts +191 -0
- package/src/resource-cache.ts +76 -0
- package/src/review-cli.ts +256 -0
- package/src/review.ts +376 -0
- package/src/runtime-metrics.ts +386 -0
- package/src/scope.ts +192 -0
- package/src/sentry-activity.ts +234 -0
- package/src/sentry.ts +545 -0
- package/src/service-release.ts +18 -0
- package/src/setup-cli.ts +58 -0
- package/src/setup-kit.cjs +163 -0
- package/src/setup-kit.d.cts +32 -0
- package/src/source-index.ts +208 -0
- package/src/source-review-git.ts +131 -0
- package/src/source-review.ts +736 -0
- package/src/telemetry.ts +68 -0
- package/src/time-window.ts +51 -0
- package/src/trace-evidence.ts +80 -0
- package/src/trace-model.ts +26 -0
- package/src/tracing.ts +165 -0
- package/src/work-check.ts +149 -0
- package/src/work-cli.ts +229 -0
- package/src/work-context.ts +753 -0
- package/src/work-intents.ts +196 -0
- package/src/work-items.ts +151 -0
- package/src/work-lock-check.ts +549 -0
- package/src/work-locks.ts +108 -0
- package/src/work-model.ts +466 -0
- package/src/work-review-git.ts +130 -0
- package/src/work-review.ts +573 -0
- package/src/work-switcher-model.ts +121 -0
- package/src/work-switcher.ts +191 -0
- package/src/working-cli.ts +38 -0
- package/src/working-code.ts +582 -0
- package/src/workspace-notes.ts +203 -0
- package/src/workspace-tests.ts +654 -0
- package/toolkit/GUIDE.md +354 -0
- package/toolkit/SKILL.md +142 -0
- package/toolkit/bin/fractory +2 -0
- package/toolkit/build.json +1 -0
package/toolkit/GUIDE.md
ADDED
|
@@ -0,0 +1,354 @@
|
|
|
1
|
+
# Fractory: repository setup and developer guide
|
|
2
|
+
|
|
3
|
+
Fractory turns a repository into a navigable map of logical black boxes. Open a block to see its parts, inspect how they interact, read its documentation, run its tests and review changes on the same map. The repository remains the source of truth; Fractory does not replace Git, the test runner or your observability backend.
|
|
4
|
+
|
|
5
|
+
## 1. Install and open a repository
|
|
6
|
+
|
|
7
|
+
Use the Mac app supplied by your team. Move Fractory.app to Applications before opening it. This private beta requires macOS 13 or newer and the build matching your Mac (arm64 for Apple Silicon; x64 for Intel). Unsigned beta builds may require an explicit exception in System Settings → Privacy & Security after attempting to open them. Follow your team's installation policy; never disable Gatekeeper globally. Signed, notarized releases avoid this setup friction.
|
|
8
|
+
|
|
9
|
+
Choose Open folder and select a local Git checkout. Fractory automatically installs its agent skill in `.agents/skills/fractory/SKILL.md`, including this guide as a reference. Existing team-customized skills are preserved. Three screens introduce the skill, offer agent-driven integration setup, and show how to ask your agent to map the product. Copy a focused `$fractory` request into Codex in this repository. No application dependencies or application modules are executed just by selecting a folder. The screen notices when the agent has generated a valid map and offers Open map. Existing mapped repositories remain directly accessible from the repository list.
|
|
10
|
+
|
|
11
|
+
The app includes its server and runtime. Git must be installed for history and comparisons. Executable tests require the repository's supported Bun or Node/Vitest toolchain and installed dependencies. GitHub CLI (`gh`) is optional if using a GitHub token or an agent's connected GitHub account.
|
|
12
|
+
|
|
13
|
+
## 2. Find the bundled CLI and install the SDK
|
|
14
|
+
|
|
15
|
+
With the app in Applications, the CLI is:
|
|
16
|
+
|
|
17
|
+
```sh
|
|
18
|
+
"/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory" doctor
|
|
19
|
+
"/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory" setup
|
|
20
|
+
"/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory" guide
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Run these from the repository root. The setup prompt contains the exact path when the app is elsewhere. In the commands below, `fractory` means this executable, or an existing repository script wrapping it. Adding its `bin` directory to your shell's PATH is optional. The CLI uses the app's embedded runtime; Node is not required just to inspect or compile a map.
|
|
24
|
+
|
|
25
|
+
Install the public CLI and annotation SDK with the repository's package manager:
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
npm install @granular-software/fractory
|
|
29
|
+
npx fractory setup --install-skill
|
|
30
|
+
npx fractory doctor
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Bun, pnpm and Yarn can install the same package. Use the pinned local package for compiler/CI consistency. The Mac app also carries the identical package as `Contents/Resources/toolkit/fractal-sdk.tgz` for offline use. No Granular service is needed. Node 22+ runs the CLI; tests and benchmark subprocesses use the repository's own runners.
|
|
34
|
+
|
|
35
|
+
## 3. Map the product without restructuring it
|
|
36
|
+
|
|
37
|
+
Inspect the real entry points, services, public APIs and tests first. Cover the largest product areas and their immediate parts before mapping one workflow deeply. Organize around responsibilities: importing data, storing it, exposing it, authorizing access. Folder names and deployment units are evidence, not automatically the logical hierarchy.
|
|
38
|
+
|
|
39
|
+
Use only the existing annotations: **Block** for a black box, **Interface** for a named way to interact with it, **Method** for an existing callable exposed through an interface, and **Process** for an existing multi-step operation. Processes can contain smaller blocks. Hosting and infrastructure stay separate from logical nesting. Contracts, auth, docs, tests and benchmarks attach to the relevant declaration.
|
|
40
|
+
|
|
41
|
+
Annotate existing classes and methods. TypeScript does not support decorators on standalone function declarations; use the equivalent function wrapper there. Do not introduce classes solely to make the map, list children manually, duplicate interface method lists, or maintain an independent graph.
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import {
|
|
45
|
+
Block,
|
|
46
|
+
Interface,
|
|
47
|
+
Method,
|
|
48
|
+
Process,
|
|
49
|
+
type InterfaceRef,
|
|
50
|
+
} from "@granular-software/fractory/annotations";
|
|
51
|
+
|
|
52
|
+
// Existing application class: its name and implementation remain yours.
|
|
53
|
+
@Block("catalog", {
|
|
54
|
+
label: "Catalog",
|
|
55
|
+
description: "Store and retrieve products.",
|
|
56
|
+
})
|
|
57
|
+
export class Catalog {
|
|
58
|
+
@Interface({
|
|
59
|
+
label: "Read products",
|
|
60
|
+
docs: "./catalog.md",
|
|
61
|
+
tests: ["./catalog.test.ts"],
|
|
62
|
+
})
|
|
63
|
+
static readonly read: InterfaceRef;
|
|
64
|
+
|
|
65
|
+
@Interface({ label: "Update products" })
|
|
66
|
+
static readonly write: InterfaceRef;
|
|
67
|
+
|
|
68
|
+
@Method(() => Catalog.read)
|
|
69
|
+
async get(id: string) {
|
|
70
|
+
/* existing implementation */ return { id };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
@Method(() => Catalog.write)
|
|
74
|
+
async save(id: string) {
|
|
75
|
+
/* existing implementation */ return { id };
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
In a different file, keep an existing standalone operation and give it a typed parent:
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import { Method, Process } from "@granular-software/fractory/annotations";
|
|
84
|
+
import { Catalog } from "./catalog";
|
|
85
|
+
|
|
86
|
+
export const importProducts = Process("catalog/import", {
|
|
87
|
+
parent: () => Catalog,
|
|
88
|
+
label: "Import products",
|
|
89
|
+
description: "Validate and save an incoming product batch.",
|
|
90
|
+
})(async function importProducts(catalog: Catalog, ids: string[]) {
|
|
91
|
+
for (const id of ids) await catalog.save(id);
|
|
92
|
+
});
|
|
93
|
+
|
|
94
|
+
export const findProduct = Method(() => Catalog.read)(
|
|
95
|
+
async function findProduct(catalog: Catalog, id: string) {
|
|
96
|
+
return catalog.get(id);
|
|
97
|
+
},
|
|
98
|
+
);
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Use stable IDs that survive file moves. Parent references and interface references may cross files. The compiler reconstructs membership, contracts and statically resolvable calls without importing application modules. Dynamic dispatch, HTTP, queues and WebSockets may not resolve automatically. Leave unverified relationships as gaps; a typed contract alone is not proof that two services communicate. Document evidence and limits rather than inventing arrows.
|
|
102
|
+
|
|
103
|
+
Every incoming connection from outside a black box must target a public interface. Direct links to a block or an internal method are rejected by compilation, map checks and worktree planning. The exact implementation member remains attached to the interface link as source evidence. Public constructors and callable blocks publish their actual signatures as entry interfaces; this does not change runtime authorization or validation.
|
|
104
|
+
|
|
105
|
+
An interface belongs to its immediate owner. Publish a nested contract through an enclosing box explicitly:
|
|
106
|
+
|
|
107
|
+
```ts
|
|
108
|
+
@Block("catalog/cache", {
|
|
109
|
+
parent: () => Catalog,
|
|
110
|
+
exposedBy: [() => Catalog],
|
|
111
|
+
label: "Product cache",
|
|
112
|
+
})
|
|
113
|
+
export class ProductCache {
|
|
114
|
+
@Interface({ label: "Read cached products" })
|
|
115
|
+
static readonly read: InterfaceRef;
|
|
116
|
+
@Method(() => ProductCache.read)
|
|
117
|
+
async get(id: string) {
|
|
118
|
+
return { id };
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
`exposedBy` on a block publishes its public surfaces through the named enclosing boxes; put it on one interface to publish only that contract. It declares a real API boundary, not a new runtime wrapper. Keep private implementation private. Fix missing-contract diagnostics at the declaration or call site instead of drawing a fake facade. Source inventory adapters may group actual module exports into an interface, preserving their declarations and exact call-site evidence.
|
|
124
|
+
|
|
125
|
+
Interfaces use a rectangular shape with small symmetric beveled corners, a single outline and a plug mark. Normal blocks retain their rounded box shape and the same selection/change colors. On a block view, its exposed interfaces occupy the boundary. Open an interface to see outside callers on the left and the implementation on the right. In worktree sketches, choose **Interface** or set `blockKind: "interface"` on a proposed block; new connections must enter an interface.
|
|
126
|
+
|
|
127
|
+
Runtime argument/result validation is optional and explicit: `@Method(() => Catalog.write, { contract: { args: argumentSchema, result: resultSchema } })`. Both schemas implement synchronous `parse`. Interface `auth` receives `{ receiver, args, context }`; retain existing authorization and use trusted host context if adding a policy. TypeScript contracts describe shapes; runtime validation and application tests enforce behavior. Do not silently add a different auth policy during mapping.
|
|
128
|
+
|
|
129
|
+
## 4. Generate, verify and keep the map current
|
|
130
|
+
|
|
131
|
+
```sh
|
|
132
|
+
fractory compile --include src --graph --write fractory.json
|
|
133
|
+
fractory compile --include src --graph --write fractory.json --check
|
|
134
|
+
fractory check
|
|
135
|
+
fractory quality --json
|
|
136
|
+
fractory coverage --missing --json
|
|
137
|
+
fractory open
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Use comma-separated source directories in `--include`, such as `apps,packages,src,lib`, and keep the same selection when generating and checking. No annotations is a setup gap, not a successful empty map. `compile --check` compares current compiler output with the saved artifact without rewriting it. `check` validates the saved definition; it does not run tests. `quality` identifies structural problems, missing purpose and absent mapped interactions. No mapped interaction is not proof of dead code.
|
|
141
|
+
|
|
142
|
+
Commit `fractory.json`, annotations and documentation. Add generation and check scripts to the repository. In CI, run the same compiler version with the same include paths and fail on stale output. Use the repository's normal toolchain and pinned SDK/compiler source for CI; the Mac executable itself is not a Linux CI dependency. The public package includes the compiled Node CLI (for example `npx fractory compile --include src --graph --write fractory.json --check`). Existing Granular repositories can keep their three generated artifacts and their existing generation/check scripts; do not replace them with a shallow standalone map.
|
|
143
|
+
|
|
144
|
+
Map coverage measures ownership of in-scope TS/JS source lines, not test coverage. Review missing source in the coverage browser. Discard generated files, vendored libraries or other irrelevant regions with an explicit reason. Do not discard real product behavior to improve the percentage. Other languages can be viewed using an externally generated definition, but this compiler's decorator and coverage discovery is for TS/JS; do not promise equivalent automatic support for every language.
|
|
145
|
+
|
|
146
|
+
## 5. Navigate and work on a block
|
|
147
|
+
|
|
148
|
+
The map is the primary workspace. Click into a block to see its contents; zoom through nested blocks or use the breadcrumb to go up. Outside callers stay distinguishable from inside parts. Leaf blocks open their details rather than an empty internal map. `⌘K` searches names and logical paths. `⌘B` toggles the block workspace; `⌘⇧H` returns to the product root (use Control instead of Command on other keyboards). Search and Workspace form one toolbar group; Metrics, Benchmarks, Worktrees, History, Sentry and Linear form a separate map group. Display settings control zoom behavior and visual density.
|
|
149
|
+
|
|
150
|
+
A block’s About view and its open map show available activity: saved local changes, errors, linked issues, code activity and named performance measurements. Click a signal to open its evidence. They reuse the overlay data and selected periods; cached, partial or unavailable sources remain explicit. Disconnected sources do not appear as healthy zeros. Historical comparisons do not borrow today’s runtime signals.
|
|
151
|
+
|
|
152
|
+
Open a block workspace for its purpose, interfaces/contracts, Connections, Notes, Tests, History and available performance evidence. Large workspace collections use Arc tree navigation grouped by logical block ownership. Direct attachments sit at the current level; shared items appear once at their common parent, with their associations retained. Search by item or block, expand a branch, and select an item to read its content. Test branch checkboxes select all runnable suites beneath them; arrow keys navigate, Space checks a row and Enter opens it. Checks inside a suite follow its real describe groups. Commits remain chronological and are grouped by month. Called by shows actual mapped incoming relationships; highlight them directly on the map. These callers are places to inspect after an interface change, not a list of proven breakages.
|
|
153
|
+
|
|
154
|
+
Right-click a block for navigation and copy actions. `⌘⇧C` copies its ID, name and source link for a Codex chat. `File → Copy Map Link` copies the current map/comparison context. Desktop links currently include the local repository path: colleagues with a different checkout location should open their own repository and navigate by the copied block ID or use Compare. Do not treat machine-local paths as universally portable links.
|
|
155
|
+
|
|
156
|
+
Markdown notes are versioned files attached to blocks, displayed as readable content and editable in the workspace. Use them for purpose, design decisions, maintenance notes and known limits. Link related attached pages and relevant blocks. Keep secrets and production payloads out of notes. Avoid a second architecture document duplicating generated contracts.
|
|
157
|
+
|
|
158
|
+
### Agent reports
|
|
159
|
+
|
|
160
|
+
Reports are repository Markdown documents tied to one or several real block IDs. Use them for findings, reviews, explanations and handoffs that the developer should read in Fractory. They are separate from editable block notes. No extra graph declaration is needed.
|
|
161
|
+
|
|
162
|
+
When developing Fractory, finish each coherent update by creating a CLI report in that update's worktree, attached to its smallest relevant blocks. Explain what changed, why, the checks actually performed and any remaining limits; return the reader link in the final handoff. This includes UI polish, map or integration setup, and skill/documentation updates. The report is part of delivering the update, without a separate request from the developer. Parent unread badges roll up automatically; attaching every ancestor is unnecessary.
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
fractory reports create --block BLOCK_ID --title 'Review findings' --file /tmp/review.md --author Codex
|
|
166
|
+
fractory reports create --block FIRST_ID --block SECOND_ID --title 'Shared finding' --stdin
|
|
167
|
+
fractory reports list --block BLOCK_ID --unread
|
|
168
|
+
fractory reports show REPORT_ID
|
|
169
|
+
fractory reports open REPORT_ID
|
|
170
|
+
fractory reports read REPORT_ID
|
|
171
|
+
fractory reports unread REPORT_ID
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
`--stdin` reads piped Markdown, not an interactive editor. `--root PATH` selects a checkout; `--file` is relative to the agent's current directory. Creation checks every block ID and returns the document plus a `fractory://` link that opens its reader. A report is an ordinary `.md` file in `docs/fractory/reports/`, with a small `fractory` front-matter mapping containing its ID, title, target IDs, creation date, optional author label and checkout HEAD. HEAD is context, not proof of an unchanged checkout or an executed test. Commit reports when they belong with the work; creation does not commit or publish anything.
|
|
175
|
+
|
|
176
|
+
A blue card badge counts unread reports on that block and its nested parts. The same report counts once at a common parent, even when attached to several children. The current map heading exposes the repository/focused-block inbox. Workspace → Docs → Reports uses the logical block tree and displays full Markdown. Source HTML and automatic remote images are disabled, as for notes.
|
|
177
|
+
|
|
178
|
+
Opening report content acknowledges that content revision for this developer. Read receipts stay in the ignored `.fractal/reports/read/` directory, separate from shared reports. CLI list/show does not acknowledge anything. Mark unread is available in the reader and CLI; a content edit also makes the report unread again. Reports with removed targets remain in the repository's Unassigned group. Historical map comparisons do not borrow today's notification badges.
|
|
179
|
+
|
|
180
|
+
## 6. Run real tests and inspect results
|
|
181
|
+
|
|
182
|
+
Attach existing test suites using `tests: ['./relative.test.ts']`. Fractory resolves paths relative to the declaring file and supports associated Bun and Vitest suites. In Tests, inspect named cases and source, select suites, run them, and read assertion failures and actual runner output. Install repository dependencies before running; opening or listing tests does not execute them.
|
|
183
|
+
|
|
184
|
+
```sh
|
|
185
|
+
fractory block BLOCK_ID --docs
|
|
186
|
+
fractory tests --block BLOCK_ID --source
|
|
187
|
+
fractory tests --block BLOCK_ID --file src/catalog.test.ts --run
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
All runnable suites are selected by default. Use Select all or Clear selection to choose a subset. The runner queues the full selection in bounded batches; Stop cancels the active batch and remaining queue. An attached suite is an association, not a claim that every method, branch or caller is covered. Passing results apply to the source/environment actually tested and become stale as code changes. Fractory does not invent tests from the map or start deployment/end-to-end tests implicitly.
|
|
191
|
+
|
|
192
|
+
## 7. Local Git, history and conceptual PR review
|
|
193
|
+
|
|
194
|
+
**Worktrees** opens the branch/worktree picker. Open one to see its blue context bar, current reports and results. **Show worktree changes** highlights committed and uncommitted edits against its starting revision. Git identifies worktrees and files, not which agent typed each line. Refresh does not require a commit. Keep untracked, staged, unstaged and committed changes distinct.
|
|
195
|
+
|
|
196
|
+
History is activity over a selected time window. Revision comparison is the difference between two versions; edits later reverted can count as activity but disappear in an endpoint diff. Read the visible mode, date range, attribution and unassigned/excluded totals. Churn is added plus deleted lines divided by the relevant starting size; it is not net growth and can exceed 100%. Changed lines do not measure quality or developer productivity.
|
|
197
|
+
|
|
198
|
+
Compare opens a picker for GitHub PRs, local branches, revisions and uncommitted work. Review changes hierarchically: product areas first, then interfaces and internal changes. Historical contracts and connections can be compared exactly only when maps/snapshots exist at both revisions. Otherwise Fractory labels a current-map footprint; it must not claim to know the old architecture. Keep generated definitions in commits and CI artifacts for future reviews.
|
|
199
|
+
|
|
200
|
+
```sh
|
|
201
|
+
fractory review --base main --head HEAD --open
|
|
202
|
+
fractory review --pr 123 --open
|
|
203
|
+
fractory review --base BASE_SHA --head HEAD_SHA --title 'PR title' --url https://github.com/owner/repo/pull/123 --open
|
|
204
|
+
```
|
|
205
|
+
|
|
206
|
+
The CLI prints the selected immutable refs and a desktop link. `--pr` uses your signed-in `gh` account; an agent can instead use its GitHub connector and pass resolved SHAs. Fetch only missing selected refs/ancestry when needed. Do not check out a PR, create worktrees or scan all history just to view it. The comparison does not include uncommitted work unless that source is explicitly selected.
|
|
207
|
+
|
|
208
|
+
## 8. Connect each repository's integrations
|
|
209
|
+
|
|
210
|
+
Ask `$fractory Connect GitHub, Sentry and Linear for this repository.` The agent handles discovery, provider authorization and verification. You handle unavoidable account login/MFA/consent only. Credentials are encrypted on this Mac, outside Git, separately for each repository. No tokens belong in chat, source, a URL or shell arguments.
|
|
211
|
+
|
|
212
|
+
```sh
|
|
213
|
+
fractory integrations status
|
|
214
|
+
fractory integrations connect all --auto
|
|
215
|
+
fractory integrations connect github --login
|
|
216
|
+
fractory integrations connect sentry --login --org ORG --projects PROJECT_A,PROJECT_B
|
|
217
|
+
fractory integrations connect linear --token-stdin --workspace-id WORKSPACE_ID
|
|
218
|
+
fractory integrations check all
|
|
219
|
+
fractory integrations disconnect linear
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
`--auto` reuses saved credentials, provider CLI sessions and allowlisted repository environment values. Read access is verified before saving. GitHub is checked against the chosen repository, Sentry against the selected organization/projects, and Linear against its actual workspace. Ambiguous selection or missing authorization is a structured agent task, not a successful connection. `--token-stdin` is for a secure agent-owned pipe; never ask the user to paste a key. Status is redacted. The CLI uses a private local channel to the Mac app; the repository must be registered. Advanced settings remain in Integrations (`⌘,`).
|
|
223
|
+
|
|
224
|
+
**GitHub:** use the official `gh` browser login. The CLI derives owner/repository from the Git remote where possible. Organization SSO may need consent. Verify an actual PR appears in Compare. Local Git works independently of GitHub.
|
|
225
|
+
|
|
226
|
+
**Sentry:** the new official `sentry` CLI supports read-only browser authorization; this differs from legacy `sentry-cli`. Keep OAuth refresh owned by that CLI. Existing `SENTRY_AUTH_TOKEN`, repository settings or standard legacy CLI credentials can also be reused. Select this repository's project slugs explicitly; don't attach every organization project. Reliable leaf-block assignment requires deployed release/commit IDs and original source frames. Source-map upload credentials belong in CI. Unresolved frames and missing historical maps remain unmatched. Automatic setup targets sentry.io; self-hosted installations need existing server-side host configuration and direct credentials.
|
|
227
|
+
|
|
228
|
+
**Linear:** reuse saved Fractory access or `LINEAR_API_KEY`. Otherwise the agent verifies the browser account/workspace and acquires read-only access in Security & access, then hands the credential to the CLI via stdin. Codex's own OAuth credential is not exportable Fractory access. Lack of workspace membership remains an explicit blocker. Link issues to real block IDs in `fractal.issues.json`; titles alone cannot reliably assign them. Recorded imports are snapshots, not automatic refresh. Onboarding does not create external issues or send messages.
|
|
229
|
+
|
|
230
|
+
**Metrics:** optional Prometheus-compatible read endpoint (including Grafana Cloud), environment, username if using Basic auth and read token. Keep telemetry write credentials in the product's runtime/CI configuration. A successful query connection does not prove that the expected instruments are arriving. Verify real recent samples for a relevant block, correct units and environment, plus source freshness. No data is not zero. Native Cloudflare log/trace export alone does not establish custom application metrics.
|
|
231
|
+
|
|
232
|
+
These providers are optional: first get a useful map, documentation, tests and local Git working, then enable available connections. A disconnected provider should remain clearly disconnected, not break navigation or claim a healthy zero.
|
|
233
|
+
|
|
234
|
+
## 9. Benchmarks and metrics
|
|
235
|
+
|
|
236
|
+
Benchmarks repeat a fixed workload; metrics observe real traffic. Attach ordinary `.bench.ts` files to relevant blocks with `benchmarks: ['./example.bench.ts']`. Product benchmarks export an operation with a name, versioned fixture, `prepare`, `run`, `cleanup`, and an identified test environment/revision. Setup and cleanup stay outside the measured operation. Verify correctness and preserve failed attempts. Compare matching fixtures, workloads, timing sources and environment configuration. Repeated runs with too much variance are inconclusive, not an automatic regression. Small sample sets do not justify a meaningful p95. Function microbenchmarks can use Tinybench; do not present them as end-to-end product timings.
|
|
237
|
+
|
|
238
|
+
```sh
|
|
239
|
+
fractory benchmark --block BLOCK_ID --json
|
|
240
|
+
fractory benchmark --block BLOCK_ID --file src/example.bench.ts --run
|
|
241
|
+
fractory benchmark --compare SELECTED_RUN_ID --against REFERENCE_RUN_ID --json
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
Select two runs in the block workspace to compare measured duration, individual attempts and phases. Same-deployment comparisons are labeled repeatability checks. A parent shows named measurements, not a combined score. Only run remote benchmarks against an explicitly approved test target. Existing Granular fixtures or deployments are not defaults for other repositories. Dedicated infrastructure provisioning and performance comparisons across deployed revisions require their own product-specific setup and verification.
|
|
245
|
+
|
|
246
|
+
Live metrics should measure named outcomes: build queue wait versus execution, usable-session preparation, import throughput/backlog, query latency, action failures. Use standard OpenTelemetry counters/histograms/gauges and an existing telemetry backend. Attach read queries using `fractory.metrics.json`. For example, after verifying that your backend really publishes `catalog_queue_depth` with an `environment` label:
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"schema": "fractory.metrics.v1",
|
|
251
|
+
"gauges": [
|
|
252
|
+
{
|
|
253
|
+
"id": "catalog-backlog",
|
|
254
|
+
"label": "Products waiting to import",
|
|
255
|
+
"unit": "products",
|
|
256
|
+
"aggregation": "sum",
|
|
257
|
+
"sources": [
|
|
258
|
+
{
|
|
259
|
+
"block": "catalog/import",
|
|
260
|
+
"query": "sum(catalog_queue_depth{environment=$environment})"
|
|
261
|
+
}
|
|
262
|
+
]
|
|
263
|
+
}
|
|
264
|
+
]
|
|
265
|
+
}
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Use an actual mapped ID and metric name. `$environment` is substituted by Fractory using the selected metrics environment. Sum only additive measurements such as disjoint queue inventories; never sum unrelated latencies. The current query adapter also supports `max`, with visible semantics when measurements roll up to parents. Keep the file small: currently at most 12 measurements and 20 source queries in total.
|
|
269
|
+
|
|
270
|
+
The SDK exports `otel-metrics` and `telemetry` for supported Node/Cloudflare hosts. Avoid payloads, object IDs and unbounded metric labels. Queue depth comes from authoritative queue/storage state. Metrics and benchmark UI are still beta; do not claim production verification, automatic PR performance comparison or statistical guarantees beyond actual recorded evidence.
|
|
271
|
+
|
|
272
|
+
## 10. Working with agents and maintaining the installation
|
|
273
|
+
|
|
274
|
+
```sh
|
|
275
|
+
fractory setup --install-skill
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
This installs `.agents/skills/fractory/SKILL.md` only if no skill exists. Read and merge an existing skill deliberately; never overwrite team guidance automatically. An agent can use the same block IDs, Markdown, real test results and comparison URLs as the human map. Ask it to start with a block's context and real connections, make the change, regenerate/check the map, then run relevant tests. No separate binding registry or agent-only architecture is needed.
|
|
279
|
+
|
|
280
|
+
Repository annotations, generated maps, notes and issue links travel through Git. Each person configures their own provider access on their own Mac. Updating Fractory replaces the app in Applications while keeping recent repositories and encrypted settings in `~/Library/Application Support/Fractory`. Updates are manual in this beta; no public upload, automatic updater or team credential synchronization is implied. Keep the old app until a new build is verified.
|
|
281
|
+
|
|
282
|
+
Help → Show Logs helps diagnose startup issues; review logs before sharing them. Reopen a repository after changing environment files. Fractory does not need the Granular dashboard or a dev server running. If the map is missing/stale, regenerate it; if a runner is missing, install the repository's required toolchain; if a provider fails, use Save & check and verify actual provider data. Report remaining gaps plainly.
|
|
283
|
+
|
|
284
|
+
## Setup is complete when
|
|
285
|
+
|
|
286
|
+
- The product's largest areas and their immediate parts are understandable on the map, with verified callers and explicit gaps.
|
|
287
|
+
- Generated output is reproducible and stale output fails a CI check.
|
|
288
|
+
- At least one attached Markdown document renders and one real existing test runs with named results.
|
|
289
|
+
- A saved local edit appears in its worktree view and a meaningful comparison opens with its evidence limits visible.
|
|
290
|
+
- Available connectors have been checked against actual repository/project data; unavailable ones remain explicitly disconnected.
|
|
291
|
+
- Each enabled metric/benchmark has a clear meaning, source, environment and reproducible definition. Unconfigured optional features are recorded as gaps, not fake successes.
|
|
292
|
+
|
|
293
|
+
References: [Fractory's standard metrics model](https://opentelemetry.io/docs/concepts/signals/metrics/), [GitHub fine-grained tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), [Sentry authentication](https://docs.sentry.io/api/auth/), [Linear authentication](https://linear.app/developers/graphql), [Mac app installation](https://support.apple.com/102445).
|
|
294
|
+
|
|
295
|
+
## Start work from the map
|
|
296
|
+
|
|
297
|
+
Main is the reference view. Cmd/Ctrl-click blocks at any level, choose **Start worktree**, name the work, then **Copy full brief** in the blue work bar. The branch and worktree form one work context. An existing worktree can be selected from Main → Worktrees. Proposed blocks and links are dashed intentions, not compiled code.
|
|
298
|
+
|
|
299
|
+
```sh
|
|
300
|
+
fractory work list
|
|
301
|
+
fractory work create --title 'Improve build reuse' --block BLOCK_ID
|
|
302
|
+
fractory work show WORK_ID
|
|
303
|
+
fractory work handoff WORK_ID
|
|
304
|
+
fractory work plan WORK_ID --file plan.json --revision REVISION
|
|
305
|
+
fractory work check WORK_ID
|
|
306
|
+
fractory work review WORK_ID
|
|
307
|
+
fractory work open WORK_ID
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
Work in the exact directory returned by `work create` or the handoff. Do not switch the original checkout or create another worktree for the same request. Read its scope and proposed changes before editing. Parent scope includes descendants; the work plan lives in `docs/fractory/work/WORK_ID.json`. Change it through `work plan` with the current revision from `work show`, preserving unrelated proposals. The plan JSON contains `proposals` and optional `scope`; proposals have a `proposal:UUID` ID, kind `block`, `connection`, or `annotation`, a label and note. Blocks specify `parent`; connections specify `source` and `target`; annotations specify `target` and `change` (`change` or `remove`). References are stable block/proposal IDs. Do not manually add these intentions to the compiled map.
|
|
311
|
+
|
|
312
|
+
Implement the intent using the existing code/decorators, regenerate the real map, run the actual associated tests and `work check` before committing. This command exits nonzero for outside, shared or unassigned files. Existing files use pinned baseline ownership, so editing the map cannot silently claim them. File-level ownership is conservative and is not a filesystem sandbox or a protected merge check. Report uncertainty and request a scope adjustment when necessary; do not hide it by remapping unrelated files. To enforce a merge policy, the repository must run the check in its trusted CI using the pinned baseline, independently of agent-edited plan files.
|
|
313
|
+
|
|
314
|
+
Create reports from inside that worktree. Its tests, benchmark results, local changes and report inbox remain separate. Production telemetry is not borrowed by an undeployed branch. Main reads committed notes/reports; when the base predates a committed map, the interface labels the reviewed-map fallback and cannot prove historical contracts. A copied bootstrap map must be regenerated before claiming current code alignment.
|
|
315
|
+
|
|
316
|
+
The Mac app detects the branch’s PR automatically through the repository’s GitHub connection. Its number, title and Draft/Open/Merged/Closed state appear as a direct GitHub link in the blue worktree bar. Detection checks the exact head repository and remote branch, including forks and unpushed local changes; it refreshes in the background while the app is visible. Several open matches remain a choice. No match adds no control; an unavailable GitHub connection offers Integrations. No URL-pasting step is required. Existing `work pr` records remain readable for compatibility, but they are not treated as verified GitHub state. `work review` returns a Markdown review summary and a deep link for the PR description; publish it only within the user's authorized PR workflow. The deep link needs the developer's local repository/work context; it is not a hosted public preview. Legacy immutable revision/PR comparisons remain available through `fractory review`.
|
|
317
|
+
|
|
318
|
+
### Planning in an existing checkout
|
|
319
|
+
|
|
320
|
+
Open **Worktrees** and choose the existing checkout. Use the blue canvas tools or right-click a block to add it to the work. Fractory attaches the plan to that checkout without changing its branch, staged changes or local files. CLI equivalent: `fractory work adopt TREE_ID --block BLOCK_ID`.
|
|
321
|
+
|
|
322
|
+
Comments stay attached to their target, support replies and can be resolved or reopened. Cmd/Ctrl-Z and Shift-Cmd/Ctrl-Z undo and redo your plan edits; native text-field undo remains unchanged. External agent plan edits clear local undo history to avoid overwriting them. Copy full brief is a fresh complete snapshot, including replies and resolved comments; old clipboard copies do not update.
|
|
323
|
+
|
|
324
|
+
**Show worktree changes** compares the starting Git revision with saved code. Filter Implementation, Interfaces or Connections to highlight the map. The evidence tree follows logical block nesting and shows changed declarations. Needs checking contains stale anchors, inferred returns and changed unresolved calls; unassigned code remains accounted for. This bounded analysis does not execute code or claim dynamic dispatch or full type compatibility. Unchanged polls reuse review results and immutable Git blobs.
|
|
325
|
+
|
|
326
|
+
Blue controls act on the worktree. Neutral **Metrics** and **Sentry** buttons return to Main before opening production data; their tooltips identify this context.
|
|
327
|
+
|
|
328
|
+
### Finding current work
|
|
329
|
+
|
|
330
|
+
**Worktrees** opens a compact switcher. Recent shows up to eight active or planned contexts and work opened or edited in the last 30 days. Older checkouts remain under Worktrees. Search by a work name, block, branch or checkout path; use arrow keys and Enter to open. **Worktrees** includes every local checkout, while **Branches** exposes branches without a checkout and marks them read-only. **Main** returns to the reference map. Names and commit metadata appear first; cached local status follows. A Local edits label means saved Git changes, not proof that an agent is currently running. Unnamed detached worktrees show related blocks and their last commit; Fractory does not invent task titles.
|
|
331
|
+
|
|
332
|
+
## Review intentions against implementation
|
|
333
|
+
|
|
334
|
+
The blue worktree view has a **Plan** section grouped by block. Select an intention, choose **Link implementation**, then pick its actual block or connection directly on the map. Confirm **Done**, or **Drop** an intention while keeping its original request. **Reopen** puts it back in the active plan. A completed sketch gives way to the linked real block; pending proposed connections follow that explicit link. Unfinished nested sketches retain their containing block.
|
|
335
|
+
|
|
336
|
+
**Done** records a confirmation and a fingerprint of the request, current mapped source and attached files. It is not a test pass or proof of behavior. A stale source reference must be regenerated before confirmation. Later changes to that request or implementation become **Needs recheck**; changes outside the linked source files do not invalidate it. Resolving a comment thread only closes the discussion. It does not mark an intention implemented.
|
|
337
|
+
|
|
338
|
+
```sh
|
|
339
|
+
fractory work show WORK_ID
|
|
340
|
+
fractory work intent WORK_ID --proposal PROPOSAL_ID --status planned --implementation BLOCK_OR_CONNECTION_ID --revision REVISION
|
|
341
|
+
fractory work intent WORK_ID --proposal PROPOSAL_ID --status done --revision REVISION
|
|
342
|
+
fractory work intent WORK_ID --proposal PROPOSAL_ID --status dropped --revision REVISION
|
|
343
|
+
fractory work review WORK_ID
|
|
344
|
+
```
|
|
345
|
+
|
|
346
|
+
Use the latest revision returned by each command. `work show`, `work handoff` and `work review` expose the same current states. Continue planned items and those needing recheck; keep done and dropped decisions as records. Existing local checks remain advisory; trusted CI and protected-branch enforcement are separate.
|
|
347
|
+
|
|
348
|
+
## Canvas selection and drawing
|
|
349
|
+
|
|
350
|
+
Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior. Blue rings and a light blue fill identify the current selection. Click empty canvas to clear it; the next selection starts empty even when those blocks belong to the saved worktree. Cmd/Ctrl-click a selected child to exclude its subtree, or select inside that exclusion to reinclude a smaller part. On Main, Start worktree uses these selected block rules. In a worktree, Update worktree selection explicitly applies them as the saved scope. Context-menu Add/Exclude edits saved membership independently of canvas selection.
|
|
351
|
+
|
|
352
|
+
Work plans store positive `scope` IDs and optional `excluded` IDs. The nearest ancestor rule wins. Preserve both through CLI plan updates; `work handoff` and `work check` use the same rules. A parent may remain in scope while a child is explicitly excluded.
|
|
353
|
+
|
|
354
|
+
The blue Block tool previews placement before a click. Name the block directly on the card. Connect by dragging blue handles or clicking a source and destination; name the connection on its wire. Enter or blur saves the name; Escape cancels a new unnamed sketch. Plan saves are ordered and show failures rather than silently discarding fast actions.
|
package/toolkit/SKILL.md
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: fractory
|
|
3
|
+
description: Set up Fractory, connect GitHub/Sentry/Linear securely, map the product as nested logical blocks, inspect docs and real tests, and open conceptual branch/PR/local comparisons. Use for block-centered development and map freshness.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
<!-- fractory-managed-skill -->
|
|
7
|
+
|
|
8
|
+
# Fractory
|
|
9
|
+
|
|
10
|
+
Use stable block IDs, real source ownership and verified connections. Preserve existing functions, classes, files and package manager. Opening repository setup installs this skill automatically; do not make the user install it or import a map.
|
|
11
|
+
|
|
12
|
+
Find existing `fractal`/`fractory` repository scripts first. The Mac app also ships `/Applications/Fractory.app/Contents/Resources/toolkit/bin/fractory` (quote the full path); use its actual location if installed elsewhere. Examples below call it `fractory`.
|
|
13
|
+
|
|
14
|
+
Read [the complete guide](references/fractory-guide.md) for SDK syntax, compiler/CI, docs/tests, Git review, coverage, integrations, metrics and benchmarks. `fractory guide` also returns it.
|
|
15
|
+
|
|
16
|
+
## First map
|
|
17
|
+
|
|
18
|
+
Run `fractory doctor`. Inspect the actual code and existing generation scripts. Map the whole product shallowly first, then nest logical responsibilities. Annotate existing code with blocks, interfaces, methods and processes; attach docs, executable tests and resources. No separate manual graph, duplicated method lists, invented callers or file-tree nesting. Unknown dynamic interactions remain gaps. Install the bundled portable SDK only if absent, reproducibly for teammates. Generate and verify the map, run a real test, add freshness checks to existing CI, then `fractory open`. Optional integrations do not block mapping or local Git.
|
|
19
|
+
|
|
20
|
+
## Connect tools for the user
|
|
21
|
+
|
|
22
|
+
```sh
|
|
23
|
+
fractory integrations status
|
|
24
|
+
fractory integrations connect all --auto
|
|
25
|
+
fractory integrations connect github --login
|
|
26
|
+
fractory integrations connect sentry --login --org ORG --projects PROJECT_A,PROJECT_B
|
|
27
|
+
fractory integrations check all
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
The repository must be registered in Fractory. The CLI opens the Mac app when needed, discovers provider CLI logins and allowlisted repository environment credentials, verifies read access, and saves encrypted per-repository credentials through a private local channel. Status never includes tokens. GitHub and Sentry login use the official `gh` and new `sentry` CLIs; `sentry` is different from legacy `sentry-cli`. If missing, install the official CLI using its documented method. Request read-only scopes and let the CLI own OAuth refresh.
|
|
31
|
+
|
|
32
|
+
Treat structured connection failures as actions for you, not chores for the user. Verify the intended account, GitHub repository, Sentry organization/projects and Linear workspace. Do not guess between accounts or broaden permissions to get a green status. Only unavoidable login, MFA or provider consent belongs to the user.
|
|
33
|
+
|
|
34
|
+
For Linear, first reuse saved Fractory access or `LINEAR_API_KEY`. If absent, use browser automation to verify the signed-in account and workspace, then acquire approved read-only access in Security & access. A Codex connector OAuth credential is separate; never extract or repurpose it. Missing workspace membership is an explicit blocker, not a reason to create a workspace.
|
|
35
|
+
|
|
36
|
+
An agent-owned secure pipe can hand the acquired credential to Fractory:
|
|
37
|
+
|
|
38
|
+
```sh
|
|
39
|
+
fractory integrations connect linear --token-stdin --workspace-id WORKSPACE_ID
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Never put tokens in command arguments, logs, transcripts, prompts, links, clipboard prompts, source files or Git. Do not echo a secret to the terminal. Prefer an in-memory pipe from the authorized credential source. If the environment cannot transfer it without disclosure, report that specific limitation instead of asking the user to paste a key. The CLI verifies workspace identity before saving. Verify real data after setup. Configured credentials, recorded snapshots and automatic refresh are different states. External issue creation, messages and product deployment require separate authorization.
|
|
43
|
+
|
|
44
|
+
## Daily block work
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
fractory block BLOCK_ID --docs
|
|
48
|
+
fractory tests --block BLOCK_ID --source
|
|
49
|
+
fractory tests --block BLOCK_ID --file PATH --run
|
|
50
|
+
fractory open --block BLOCK_ID
|
|
51
|
+
fractory review --pr NUMBER --open
|
|
52
|
+
fractory review --base main --head HEAD --open
|
|
53
|
+
fractory working --json
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Read Markdown content and named test results, not filenames alone. Test associations are not measured coverage. Prefer connected GitHub tools for immutable PR identities, otherwise use `gh`. Review without creating a worktree or checking out a PR; fetch only missing selected refs. Handle metadata as data with structured arguments or proper shell quoting. Verify the map link opens, and distinguish exact historical maps from current-map footprints.
|
|
57
|
+
|
|
58
|
+
After edits, run existing generation/check scripts and relevant tests, then publish the update report described below. Standalone example:
|
|
59
|
+
|
|
60
|
+
```sh
|
|
61
|
+
fractory compile --include src --graph --write fractory.json
|
|
62
|
+
fractory compile --include src --graph --write fractory.json --check
|
|
63
|
+
fractory quality --json
|
|
64
|
+
fractory coverage --missing --json
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Match actual include paths; preserve richer existing pipelines. Ownership coverage is not test coverage. Discard only reviewed irrelevant source with a reason. Metrics observe actual traffic; benchmarks repeat fixed workloads. Preserve missing data, failures and inconclusive comparisons.
|
|
68
|
+
|
|
69
|
+
## Reports for developers
|
|
70
|
+
|
|
71
|
+
Every update to Fractory needs a developer-readable report created through the CLI before the final handoff, without waiting for the user to ask. This includes implementation, UI polish, mapping, integration setup, and skill or documentation changes. Group related edits into one report per coherent update, written from the exact worktree where the change was made. Explain the resulting behavior, why it changed, verification actually performed, and remaining limits or unfinished work. Include the report link in the handoff so the developer can read it in Fractory.
|
|
72
|
+
|
|
73
|
+
Also use reports for requested findings, reviews and handoffs that should remain attached to the factory. Use ordinary Markdown and the CLI, without another binding list or manually constructed metadata.
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
fractory reports create --block BLOCK_ID --title 'Review findings' --file /tmp/review.md --author Codex
|
|
77
|
+
fractory reports list --block BLOCK_ID --unread
|
|
78
|
+
fractory reports show REPORT_ID
|
|
79
|
+
fractory reports open REPORT_ID
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Choose the smallest meaningful existing block. Repeat `--block` only when a report really concerns several blocks. Parent badges roll up automatically and count a shared report once: do not attach every ancestor. State what you observed, relevant evidence, tests actually run and unresolved limits. Do not invent validation or include secrets. The create result includes its Markdown path and a reader deep link; optional `--open` displays it immediately.
|
|
83
|
+
|
|
84
|
+
Reports live in `docs/fractory/reports/` and can be committed with the work. The developer reads rendered Markdown from a card badge or Workspace → Docs → Reports. Opening the content marks that revision read locally; editing Markdown makes it unread again. CLI list/show never clear notifications. Use `fractory reports read REPORT_ID` or `unread REPORT_ID` only when the user asks to change read status. Removed targets remain visible in the repository inbox; use current stable IDs for new reports.
|
|
85
|
+
|
|
86
|
+
## Start work from the map
|
|
87
|
+
|
|
88
|
+
Main is the reference view. Cmd/Ctrl-click blocks at any level, choose **Start worktree**, name the work, then **Copy full brief** in the blue work bar. The branch and worktree form one work context. An existing worktree can be selected from **Worktrees** in the toolbar. Adding a block or comment there attaches a plan in place; it does not create another branch or checkout. Proposed blocks and links are dashed intentions, not compiled code. Use the blue floating toolbar to place a block on the canvas, connect two cards, or attach a comment to a block. Right-click an existing block to add it to this worktree. **Copy full brief** always copies a fresh complete snapshot of the folder, branch, selected blocks, all proposals and attached comments. It never copies only a delta. Copy again after editing; an earlier clipboard or Codex message does not update automatically. **Check changed blocks** reports changed files outside the selected blocks or without clear ownership. **Show worktree changes** compares saved code with the starting revision. Implementation, interface declaration and proven connection changes can be highlighted separately. Change evidence is grouped by logical block, including before/after signatures. Stale anchors, inferred return types and dynamic or unmapped changed calls remain under Needs checking; this is not proof of full type compatibility. Fractory setup and incompletely mapped files remain visible separately.
|
|
89
|
+
|
|
90
|
+
```sh
|
|
91
|
+
fractory work list
|
|
92
|
+
fractory work create --title 'Improve build reuse' --block BLOCK_ID
|
|
93
|
+
fractory work adopt TREE_ID --block BLOCK_ID
|
|
94
|
+
fractory work show WORK_ID
|
|
95
|
+
fractory work handoff WORK_ID
|
|
96
|
+
fractory work plan WORK_ID --file plan.json --revision REVISION
|
|
97
|
+
fractory work check WORK_ID
|
|
98
|
+
fractory work review WORK_ID
|
|
99
|
+
fractory work open WORK_ID
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Work in the exact directory returned by `work create` or the handoff. Do not switch the original checkout or create another worktree for the same request. Read its scope and proposed changes before editing. Parent scope includes descendants; the work plan lives in `docs/fractory/work/WORK_ID.json`. Change it through `work plan` with the current revision from `work show`, preserving unrelated proposals. The plan JSON contains `proposals` and optional `scope`; proposals have a `proposal:UUID` ID, kind `block`, `connection`, or `annotation`, a label and note. Blocks specify `parent`; connections specify `source` and `target`; annotations specify `target` and `change` (`change` or `remove`). Comments form a thread: each annotation has its own ID; optional `createdAt` and `resolved` preserve time and resolution. Multiple comments can target the same block or proposed connection. Undo/redo affects local plan edits only, never source code or external agent changes. References are stable block/proposal IDs. Do not manually add these intentions to the compiled map.
|
|
103
|
+
|
|
104
|
+
Implement the intent using the existing code/decorators, regenerate the real map, run the actual associated tests and `work check` before committing. This command exits nonzero for outside, shared or unassigned files. Existing files use pinned baseline ownership, so editing the map cannot silently claim them. File-level ownership is conservative and is not a filesystem sandbox or a protected merge check. Report uncertainty and request a scope adjustment when necessary; do not hide it by remapping unrelated files. To enforce a merge policy, the repository must run the check in its trusted CI using the pinned baseline, independently of agent-edited plan files.
|
|
105
|
+
|
|
106
|
+
Create reports from inside that worktree. Its tests, benchmark results, local changes and report inbox remain separate. Blue toolbar actions follow the current worktree. Neutral Metrics and Sentry buttons open deployed data on Main; production telemetry is not borrowed by an undeployed branch. Main reads committed notes/reports; when the base predates a committed map, the CLI records that structure comes from a reviewed fallback; historical contracts cannot be proved. A copied bootstrap map must be regenerated before claiming current code alignment.
|
|
107
|
+
|
|
108
|
+
The Mac app detects the branch’s PR automatically through the repository’s GitHub connection. Its number, title and Draft/Open/Merged/Closed state appear as a direct GitHub link in the blue worktree bar. Detection checks the exact head repository and remote branch, including forks and unpushed local changes; it refreshes in the background while the app is visible. Several open matches remain a choice. No match adds no control; an unavailable GitHub connection offers Integrations. No URL-pasting step is required. Existing `work pr` records remain readable for compatibility, but they are not treated as verified GitHub state. `work review` returns a Markdown review summary and a deep link for the PR description; publish it only within the user's authorized PR workflow. The deep link needs the developer's local repository/work context; it is not a hosted public preview. Legacy immutable revision/PR comparisons remain available through `fractory review`.
|
|
109
|
+
|
|
110
|
+
## Review intentions against implementation
|
|
111
|
+
|
|
112
|
+
The blue worktree view has a **Plan** section grouped by block. Select an intention, choose **Link implementation**, then pick its actual block or connection directly on the map. Confirm **Done**, or **Drop** an intention while keeping its original request. **Reopen** puts it back in the active plan. A completed sketch gives way to the linked real block; pending proposed connections follow that explicit link. Unfinished nested sketches retain their containing block.
|
|
113
|
+
|
|
114
|
+
**Done** records a confirmation and a fingerprint of the request, current mapped source and attached files. It is not a test pass or proof of behavior. A stale source reference must be regenerated before confirmation. Later changes to that request or implementation become **Needs recheck**; changes outside the linked source files do not invalidate it. Resolving a comment thread only closes the discussion. It does not mark an intention implemented.
|
|
115
|
+
|
|
116
|
+
```sh
|
|
117
|
+
fractory work show WORK_ID
|
|
118
|
+
fractory work intent WORK_ID --proposal PROPOSAL_ID --status planned --implementation BLOCK_OR_CONNECTION_ID --revision REVISION
|
|
119
|
+
fractory work intent WORK_ID --proposal PROPOSAL_ID --status done --revision REVISION
|
|
120
|
+
fractory work intent WORK_ID --proposal PROPOSAL_ID --status dropped --revision REVISION
|
|
121
|
+
fractory work review WORK_ID
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Use the latest revision returned by each command. `work show`, `work handoff` and `work review` expose the same current states. Continue planned items and those needing recheck; keep done and dropped decisions as records. Existing local checks remain advisory; trusted CI and protected-branch enforcement are separate.
|
|
125
|
+
|
|
126
|
+
## Canvas selection and drawing
|
|
127
|
+
|
|
128
|
+
Cmd/Ctrl-click selects a block and its descendants. Cmd/Ctrl-A selects the inside blocks at the current map level; outside connections are not selected. Text fields keep normal Select All behavior. Blue rings and a light blue fill identify the current selection. Click empty canvas to clear it; the next selection starts empty even when those blocks belong to the saved worktree. Cmd/Ctrl-click a selected child to exclude its subtree, or select inside that exclusion to reinclude a smaller part. On Main, Start worktree uses these selected block rules. In a worktree, Update worktree selection explicitly applies them as the saved scope. Context-menu Add/Exclude edits saved membership independently of canvas selection.
|
|
129
|
+
|
|
130
|
+
Work plans store positive `scope` IDs and optional `excluded` IDs. The nearest ancestor rule wins. Preserve both through CLI plan updates; `work handoff` and `work check` use the same rules. A parent may remain in scope while a child is explicitly excluded.
|
|
131
|
+
|
|
132
|
+
The blue Block tool previews placement before a click. Name the block directly on the card. Connect by dragging blue handles or clicking a source and destination; name the connection on its wire. Enter or blur saves the name; Escape cancels a new unnamed sketch. Plan saves are ordered and show failures rather than silently discarding fast actions.
|
|
133
|
+
|
|
134
|
+
## Interfaces and locked work
|
|
135
|
+
|
|
136
|
+
Model a responsibility as a black box with public interfaces and internal implementation. All incoming links from outside a black box target an interface ID, never its block or an internal method. Compilation, map checks and new worktree links enforce this. Annotate the actual callable contract; a web UI is an interface too. A web app normally contains that UI plus its rendering/state/data internals. Public constructors and callable blocks have source-backed entry interfaces. Internal methods remain internal and are reached through their declared interface.
|
|
137
|
+
|
|
138
|
+
Nested interfaces are public to their owner. To publish them through enclosing boxes, declare `exposedBy: [() => EnclosingBlock]` on the interface, or on its block to publish that block's public surfaces. Preserve exact implementation identities and source evidence behind the interface; do not invent an API to conceal an unresolved/private call. Fix a rejected link by selecting the real public interface or declaring the genuine missing contract. Unknown dynamic calls remain gaps. In a worktree, use the Interface canvas tool or a proposed block with `blockKind: "interface"`, then link callers to it. Opening an interface shows outside callers on the left and its implementation on the right.
|
|
139
|
+
|
|
140
|
+
Before changing a worktree, read its `locks` in `work show` or the full brief. A subtree lock protects the entire block and descendants; an interface contract lock protects exposed names, routes, inputs, outputs, signatures and nested public entrypoints but allows internal implementation changes. Locks take precedence over editable scope. Do not remove a lock to make a check pass. Unsupported or inferred contract evidence requires the relevant API/type/behavior check, not a claim that compatibility is proved.
|
|
141
|
+
|
|
142
|
+
`fractory work lock WORK_ID --block BLOCK_ID --revision REVISION [--note REASON]` adds or updates a lock. `work unlock` removes the explicitly named lock. `work plan` also accepts a `locks` array of `{target, kind: "subtree" | "contract", note?}`; omission preserves existing locks. Always preserve unrelated constraints. Check changed blocks/work check includes lock results, and Copy full brief/work handoff includes the full current constraints. Create the update report as described above after verification.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":"0.1.25"}
|