@nonameolsson/nightjar 0.0.0-stage → 0.2.0

package/schema/factory.schema.json

@@ -0,0 +1,437 @@
+{
+	"$schema": "https://json-schema.org/draft/2020-12/schema",
+	"type": "object",
+	"properties": {
+		"$schema": {
+			"type": "string"
+		},
+		"tracker": {
+			"oneOf": [
+				{
+					"type": "object",
+					"properties": {
+						"type": {
+							"type": "string",
+							"const": "github"
+						},
+						"repo": {
+							"description": "owner/name on GitHub; when left out, read from the origin remote",
+							"type": "string",
+							"pattern": "^[^/\\s]+\\/[^/\\s]+$"
+						}
+					},
+					"required": [
+						"type"
+					],
+					"additionalProperties": false,
+					"description": "GitHub Issues: a Feature is an issue with sub-issues, its Tickets"
+				},
+				{
+					"type": "object",
+					"properties": {
+						"type": {
+							"type": "string",
+							"const": "azure-devops"
+						},
+						"organization": {
+							"type": "string",
+							"allOf": [
+								{
+									"pattern": "\\S"
+								},
+								{
+									"pattern": "^[^/\\s:]+$"
+								}
+							],
+							"description": "The organization, as in dev.azure.com/<organization>"
+						},
+						"project": {
+							"type": "string",
+							"pattern": "\\S",
+							"description": "The project that holds the Features"
+						},
+						"featureType": {
+							"type": "string",
+							"pattern": "\\S",
+							"description": "The work item type that plays the Feature, such as Feature, Epic or Product Backlog Item"
+						},
+						"ticketType": {
+							"description": "The work item type nightjar create makes each Ticket as, such as User Story, Product Backlog Item or Issue. Left out, nightjar create makes no Tickets.",
+							"type": "string",
+							"pattern": "\\S"
+						}
+					},
+					"required": [
+						"type",
+						"organization",
+						"project",
+						"featureType"
+					],
+					"additionalProperties": false,
+					"description": "Azure DevOps Boards: a Feature is a work item of featureType, its child work items its Tickets"
+				},
+				{
+					"type": "object",
+					"properties": {
+						"type": {
+							"type": "string",
+							"const": "module"
+						},
+						"path": {
+							"type": "string",
+							"pattern": "\\S",
+							"description": "The module that builds the Tracker, as a path from the repo's root"
+						},
+						"options": {
+							"description": "Handed to the module as it is, for its own settings",
+							"type": "object",
+							"propertyNames": {
+								"type": "string"
+							},
+							"additionalProperties": {}
+						}
+					},
+					"required": [
+						"type",
+						"path"
+					],
+					"additionalProperties": false,
+					"description": "A Tracker of the repo's own, built by a module"
+				}
+			],
+			"description": "Where the Features and Tickets live"
+		},
+		"codeHost": {
+			"oneOf": [
+				{
+					"type": "object",
+					"properties": {
+						"type": {
+							"type": "string",
+							"const": "github"
+						},
+						"repo": {
+							"description": "owner/name on GitHub; when left out, read from the origin remote",
+							"type": "string",
+							"pattern": "^[^/\\s]+\\/[^/\\s]+$"
+						}
+					},
+					"required": [
+						"type"
+					],
+					"additionalProperties": false,
+					"description": "GitHub: the branch is pushed to origin and a draft pull request opened"
+				},
+				{
+					"type": "object",
+					"properties": {
+						"type": {
+							"type": "string",
+							"const": "azure-devops"
+						},
+						"organization": {
+							"type": "string",
+							"allOf": [
+								{
+									"pattern": "\\S"
+								},
+								{
+									"pattern": "^[^/\\s:]+$"
+								}
+							],
+							"description": "The organization, as in dev.azure.com/<organization>"
+						},
+						"project": {
+							"type": "string",
+							"pattern": "\\S",
+							"description": "The project that holds the repo"
+						},
+						"repo": {
+							"type": "string",
+							"pattern": "\\S",
+							"description": "The Git repo on Azure Repos, by name"
+						}
+					},
+					"required": [
+						"type",
+						"organization",
+						"project",
+						"repo"
+					],
+					"additionalProperties": false,
+					"description": "Azure Repos: the branch is pushed to the repo and a draft pull request opened, signed in as for Azure DevOps Boards"
+				},
+				{
+					"type": "object",
+					"properties": {
+						"type": {
+							"type": "string",
+							"const": "module"
+						},
+						"path": {
+							"type": "string",
+							"pattern": "\\S",
+							"description": "The module that builds the Code host, as a path from the repo's root"
+						},
+						"options": {
+							"description": "Handed to the module as it is, for its own settings",
+							"type": "object",
+							"propertyNames": {
+								"type": "string"
+							},
+							"additionalProperties": {}
+						}
+					},
+					"required": [
+						"type",
+						"path"
+					],
+					"additionalProperties": false,
+					"description": "A Code host of the repo's own, built by a module"
+				}
+			],
+			"description": "Where the branch is pushed and the draft pull request opened"
+		},
+		"check": {
+			"type": "string",
+			"pattern": "\\S",
+			"description": "The shell command that checks the work in the worktree, run after each Ticket; it fails with a non-zero exit"
+		},
+		"allowedCommands": {
+			"type": "array",
+			"items": {
+				"type": "string",
+				"pattern": "\\S"
+			},
+			"description": "The commands the agent may run, as Claude Code Bash permission patterns without Bash( ), such as \"make test\" or \"make lint *\". Committing, pushing, switching branches, the network and gh stay denied."
+		},
+		"rules": {
+			"description": "A text file, relative to the repo root, whose text is added to the agent prompt. Conventions normally live in CLAUDE.md or AGENTS.md.",
+			"type": "string",
+			"pattern": "\\S"
+		},
+		"model": {
+			"description": "The default model of every session; a Ticket's **Model:** line overrides it and --model overrides both",
+			"type": "string",
+			"pattern": "\\S"
+		},
+		"effort": {
+			"description": "The default effort of every session; a Ticket's **Effort:** line overrides it and --effort overrides both",
+			"type": "string",
+			"pattern": "\\S"
+		},
+		"review": {
+			"description": "The read-only review of the whole diff, run before the draft pull request opens",
+			"type": "object",
+			"properties": {
+				"enabled": {
+					"description": "false switches the review off; on by default",
+					"type": "boolean"
+				},
+				"model": {
+					"description": "The review session's own model; else the default model",
+					"type": "string",
+					"pattern": "\\S"
+				},
+				"effort": {
+					"description": "The review session's own effort; else the default effort",
+					"type": "string",
+					"pattern": "\\S"
+				}
+			},
+			"additionalProperties": false
+		},
+		"signals": {
+			"description": "The name each Signal has on a Tracker: a label on GitHub, a tag on Azure DevOps. Leave out the ones you do not rename. needs-triage and wontfix are refused.",
+			"default": {},
+			"type": "object",
+			"properties": {
+				"go": {
+					"default": "factory-go",
+					"description": "The Go: put on a Feature assigned to you to have it built. Give it the name of ready to use one mark for both",
+					"type": "string",
+					"pattern": "\\S"
+				},
+				"ready": {
+					"default": "ready-for-agent",
+					"description": "A Ticket that is ready to be built",
+					"type": "string",
+					"pattern": "\\S"
+				},
+				"working": {
+					"default": "agent-working",
+					"description": "Nightjar is working on it",
+					"type": "string",
+					"pattern": "\\S"
+				},
+				"needsInfo": {
+					"default": "needs-info",
+					"description": "Nightjar needs an answer to go on",
+					"type": "string",
+					"pattern": "\\S"
+				},
+				"human": {
+					"default": "ready-for-human",
+					"description": "A person has to take it from here",
+					"type": "string",
+					"pattern": "\\S"
+				}
+			},
+			"additionalProperties": false
+		},
+		"workflows": {
+			"description": "Work a repo adds to the build loop, by name. A Feature picks one with a **Workflow:** line; Nightjar still keeps the branch, the commits, the Signals and the pull request.",
+			"type": "object",
+			"propertyNames": {
+				"type": "string",
+				"pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$"
+			},
+			"additionalProperties": {
+				"type": "object",
+				"properties": {
+					"steps": {
+						"minItems": 1,
+						"type": "array",
+						"items": {
+							"type": "object",
+							"properties": {
+								"name": {
+									"type": "string",
+									"pattern": "^[^\\r\\n]*\\S[^\\r\\n]*$",
+									"description": "The name of the Step; its commit and the pull request body name it"
+								},
+								"prompt": {
+									"type": "string",
+									"pattern": "\\S",
+									"description": "What the agent is told to do, such as \"/some-skill critique\"; it may name any skill. Nightjar adds the rule that nobody is at the keyboard."
+								},
+								"point": {
+									"type": "string",
+									"enum": [
+										"afterEachTicket",
+										"afterAllTickets"
+									],
+									"description": "afterEachTicket runs after each Ticket is built; afterAllTickets runs once, after every Ticket, before the review"
+								},
+								"model": {
+									"description": "The Step's own model; else the default model",
+									"type": "string",
+									"pattern": "\\S"
+								},
+								"effort": {
+									"description": "The Step's own effort; else the default effort",
+									"type": "string",
+									"pattern": "\\S"
+								},
+								"budgetUsd": {
+									"description": "The most one run of the Step may cost in dollars; else a Ticket's budget",
+									"type": "number",
+									"exclusiveMinimum": 0
+								},
+								"until": {
+									"description": "A condition in plain words. After each round the agent reports whether it holds, and Nightjar runs the Step again until it does or maxRounds is reached",
+									"type": "string",
+									"pattern": "\\S"
+								},
+								"maxRounds": {
+									"description": "The most rounds of a Step with an until; 3 when left out",
+									"type": "integer",
+									"minimum": 1,
+									"maximum": 10
+								}
+							},
+							"required": [
+								"name",
+								"prompt",
+								"point"
+							],
+							"additionalProperties": false
+						}
+					},
+					"serve": {
+						"description": "A command started in the background in the worktree before the Workflow's Steps and stopped after them, such as a dev server. It reads its port from the variables of ports.env, so it needs ports.",
+						"type": "string",
+						"pattern": "\\S"
+					},
+					"allowedCommands": {
+						"description": "Commands the Workflow's Steps may run besides the top-level allowedCommands, as Bash permission patterns without Bash( )",
+						"type": "array",
+						"items": {
+							"type": "string",
+							"pattern": "\\S"
+						}
+					},
+					"allowedTools": {
+						"description": "Tools the Workflow's Steps may use besides the usual ones, as Claude Code permission rules. Committing, pushing, switching branches, the outside network and gh stay denied.",
+						"type": "array",
+						"items": {
+							"type": "string",
+							"pattern": "\\S"
+						}
+					},
+					"localNetwork": {
+						"description": "true lets the Workflow's Steps reach localhost, and nothing else on the network",
+						"type": "boolean"
+					}
+				},
+				"required": [
+					"steps"
+				],
+				"additionalProperties": false,
+				"description": "A named list of Steps that a Feature picks with a **Workflow:** line"
+			}
+		},
+		"defaultWorkflow": {
+			"description": "The Workflow of a Feature without a **Workflow:** line; none when left out",
+			"type": "string",
+			"pattern": "\\S"
+		},
+		"trusted": {
+			"description": "The logins whose comments reach the agent (on Azure DevOps, sign-in names such as ann@contoso.com). When set, it replaces the Tracker default (GitHub: write access; Azure DevOps: the project's Contributors group); leave it out to keep the default.",
+			"type": "array",
+			"items": {
+				"type": "string",
+				"pattern": "\\S"
+			}
+		},
+		"setup": {
+			"description": "The shell command run once in each new worktree, before the first session, such as one that installs dependencies. When it fails, the Feature stops with a comment saying why. Left out, nothing is run.",
+			"type": "string",
+			"pattern": "\\S"
+		},
+		"ports": {
+			"description": "Ports reserved for each run and held for its whole life, so that two runs on one machine never share a port. Left out, no port is held.",
+			"type": "object",
+			"properties": {
+				"count": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 100,
+					"description": "How many ports to reserve"
+				},
+				"env": {
+					"minItems": 1,
+					"type": "array",
+					"items": {
+						"type": "string",
+						"pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+					},
+					"description": "The environment variables that carry the ports to every session, the check and the setup command: the first name gets the first reserved port, the next name the next port, and so on"
+				}
+			},
+			"required": [
+				"count",
+				"env"
+			],
+			"additionalProperties": false
+		}
+	},
+	"required": [
+		"tracker",
+		"codeHost",
+		"check",
+		"allowedCommands"
+	],
+	"additionalProperties": false,
+	"title": "Nightjar factory.json"
+}

package/skills/nightjar-feature/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: nightjar-feature
+description: Write an agreed idea onto the repo's Tracker as a Nightjar Feature and its Tickets, through `nightjar create`. Use when a spec, plan or grilled idea is ready to become a Feature for Nightjar to build.
+---
+
+# Write a Feature and its Tickets
+
+Turn the idea agreed in this conversation into one Feature file and make it on the Tracker with `nightjar create`. Nightjar builds each Ticket as one commit, in Build order, on one branch.
+
+## 1. Read the repo's setup
+
+Read `factory.json` at the repo's root. Note the Tracker, and on Azure DevOps whether `tracker.ticketType` is set: without it `nightjar create` refuses, so ask the person which work item type a Ticket is (such as `User Story`) and add it to `factory.json` before step 4. Read the repo's `CLAUDE.md` or `AGENTS.md` and its glossary, if any, so titles use the repo's own words.
+
+Done when you know the Tracker and that it can make Tickets.
+
+## 2. Slice the idea into Tickets
+
+Each Ticket is a **vertical slice**: one change that builds, passes the repo's check command, and is worth a commit on its own. Order them so each one builds on the ones above it. Give each:
+
+- a title that says what changes, in the imperative;
+- what to build, enough for an agent with no other context: the files or modules it touches, the behaviour it adds;
+- acceptance criteria an agent can check from the diff and the tests;
+- the Tickets above it that must be built first;
+- `**Model:**` and `**Effort:**` lines only for a Ticket that needs a stronger or a lighter model than the repo's default.
+
+Done when every part of the agreed idea lands in exactly one Ticket, and every Ticket has acceptance criteria.
+
+## 3. Write the Feature file
+
+Write it to `.factory/plans/<short-name>.md`, in exactly this shape:
+
+```markdown
+# <Feature title>
+
+<The spec: the problem, the solution, the decisions made, and what is out of scope.>
+
+## Ticket 1: <title>
+
+**Model:** opus
+**Effort:** high
+
+<What to build.>
+
+### Acceptance criteria
+
+- [ ] <a checkable result>
+
+## Ticket 2: <title>
+
+**Blocked by:** 1
+
+<What to build.>
+
+### Acceptance criteria
+
+- [ ] <a checkable result>
+```
+
+Number the Tickets 1, 2, 3 in build order. `**Blocked by:**` names Tickets above it by number, comma separated.
+
+## 4. Check it
+
+Run `nightjar create --dry-run .factory/plans/<short-name>.md`. It names every fault with its line; fix them and run it again until it exits 0. Show the person what it says it would make.
+
+Done when the dry run exits 0 and the person says to make it.
+
+## 5. Make it
+
+Run `nightjar create .factory/plans/<short-name>.md`. It makes the Feature with no Signal and each Ticket ready, linked to its blockers, and prints each reference.
+
+If it exits 1, it names what it made before the fault: tell the person, and leave those items for them to keep or remove.
+
+Report the Feature's reference and its Tickets'. The Go is the person's: tell them to assign the Feature to themselves and give it the Go when they want it built.

package/src/status-shape.ts

@@ -0,0 +1,44 @@
+// The shape of .factory/status.json, defined once for the writer and the plugin; types only, so the plugin can import it.
+
+export type Doing =
+	| { readonly kind: 'idle'; readonly nextPollAt: string }
+	| {
+			readonly kind: 'building';
+			readonly feature: string;
+			// null while the Feature is set up and reviewed, and during a Step that runs after all Tickets
+			readonly ticket: string | null;
+			readonly step: 'setup' | 'build' | 'fix' | 'review' | 'step';
+			// a build's question round or a fix round, of how many there may be
+			readonly round: number | null;
+			readonly rounds: number | null;
+			readonly session: string | null;
+			readonly startedAt: string;
+	  }
+	| { readonly kind: 'paused'; readonly why: string; readonly until: string | null }
+	| { readonly kind: 'off' };
+
+export type Happened =
+	| { readonly kind: 'built'; readonly feature: string; readonly ticket: string }
+	| {
+			readonly kind: 'needs-info';
+			readonly feature: string;
+			readonly ticket: string | null;
+			readonly why: string;
+	  }
+	| { readonly kind: 'failed'; readonly feature: string; readonly why: string }
+	| { readonly kind: 'pull'; readonly feature: string; readonly url: string }
+	| { readonly kind: 'stale'; readonly commit: string };
+
+export type Event = Happened & { readonly seq: number; readonly at: string };
+
+export interface Status {
+	readonly at: string;
+	readonly pid: number;
+	readonly spentTodayUsd: number;
+	readonly dailyUsd: number;
+	readonly doing: Doing;
+	// the last ten, oldest first; a reader toasts each seq it has not seen
+	readonly recent: Event[];
+	// the commit of newer Nightjar code than the one running; nothing sets it yet, older files lack it
+	readonly codeMoved?: string | null;
+}