specpilot 2.2.4 → 2.3.0

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/README.md CHANGED
@@ -76,6 +76,7 @@ This AI-assisted approach ensures comprehensive, high-quality specifications tai
76
76
  | `list` | Show available templates |
77
77
  | `migrate` | Convert legacy `.project-spec` folder (rarely needed) |
78
78
  | `refine [desc]` | Refine project specifications |
79
+ | `serve` | Serve a read-only local web UI over the current project's `.specs/` |
79
80
 
80
81
  > **Tip — command aliases:** All commands have a short alias you can use instead of the full name.
81
82
  > `init` → `i`  ·  `validate` → `v`  ·  `migrate` → `m`  ·  `list` → `ls`  ·  `refine` → `ref`  ·  `archive` → `ar`  ·  `add-specs` → `add`  ·  `backfill` → `bf`
@@ -93,6 +94,7 @@ This AI-assisted approach ensures comprehensive, high-quality specifications tai
93
94
  | `archive` | `--dry-run` · `--force` |
94
95
  | `add-specs` | `--no-analysis` · `--deep-analysis` · `--no-prompts` |
95
96
  | `backfill` | `--dir` · `--specs-name` · `--dry-run` · `--no-prompts` |
97
+ | `serve` | `--port` · `--poll` · `--open` |
96
98
 
97
99
  > Run `specpilot <command> --help` for full flag descriptions and default values.
98
100
 
@@ -112,6 +114,27 @@ specpilot refine "REST API for user management" --update
112
114
  specpilot validate --fix
113
115
  ```
114
116
 
117
+ ## specpilot serve
118
+
119
+ Serve a read-only local web UI over the current project's `.specs/`. Run it from the project root (the folder that contains `.specs/`); press Ctrl+C to stop.
120
+
121
+ ```bash
122
+ specpilot serve # http://127.0.0.1:4321
123
+ specpilot serve --port 5000 --open
124
+ ```
125
+
126
+ | Option | Default | Description |
127
+ | ------------- | ------- | ---------------------------------------------------------------------------------------- |
128
+ | `--port <n>` | `4321` | Port to listen on (127.0.0.1 only) |
129
+ | `--poll <ms>` | `1000` | Change-detection interval in ms (minimum 250); polling runs only while a page is open |
130
+ | `--open` | | Open the UI in the default browser |
131
+
132
+ - **Read-only**: re-reads files on every request and writes nothing.
133
+ - **Loopback only**: binds 127.0.0.1 only; rejects any Host header other than `127.0.0.1:<port>` or `localhost:<port>` (403).
134
+ - **Live reload**: polls allowlisted files with `stat()` every `--poll` ms while a page is open, and pushes changed paths on `/api/events`; open pages update in place.
135
+ - **What it shows**: `.specs/`, `CLAUDE.md`, `AGENTS.md`, `.github/copilot-instructions.md`, `.claude/commands/`, `.claude/skills/` and `.github/prompts/`, as the files' own text.
136
+ - **Limits**: paths through symlinked folders, hidden files and `node_modules` are not shown.
137
+
115
138
  ## Supported Languages & Frameworks
116
139
 
117
140
  ### TypeScript
package/dist/cli.js CHANGED
@@ -14,6 +14,7 @@ const refine_1 = require("./commands/refine");
14
14
  const add_specs_1 = require("./commands/add-specs");
15
15
  const archive_1 = require("./commands/archive");
16
16
  const backfill_1 = require("./commands/backfill");
17
+ const serve_1 = require("./commands/serve");
17
18
  const logger_1 = require("./utils/logger");
18
19
  const packageJson = require('../package.json');
19
20
  commander_1.program
@@ -100,6 +101,14 @@ commander_1.program
100
101
  .option('--dry-run', 'Preview changes without writing any files')
101
102
  .option('--no-prompts', 'Accept suggested devPrefix silently when team.devPrefix is missing')
102
103
  .action(backfill_1.backfillCommand);
104
+ // Serve command
105
+ commander_1.program
106
+ .command('serve')
107
+ .description('Serve a read-only local web UI over this project\'s .specs/ (127.0.0.1 only)')
108
+ .option('-p, --port <number>', 'Port to listen on', '4321')
109
+ .option('--poll <ms>', 'How often to check spec files for changes, in ms (minimum 250)', '1000')
110
+ .option('--open', 'Open the UI in your default browser')
111
+ .action(serve_1.serveCommand);
103
112
  commander_1.program.addHelpText('after', `
104
113
  Aliases:
105
114
  init → i validate → v migrate → m list → ls
package/dist/cli.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,8 @@
1
+ export interface ServeOptions {
2
+ port?: string;
3
+ poll?: string;
4
+ open?: boolean;
5
+ }
6
+ /** Runs until Ctrl+C; exits the process with 1 on any startup error. */
7
+ export declare function serveCommand(options: ServeOptions): Promise<void>;
8
+ //# sourceMappingURL=serve.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"AASA,MAAM,WAAW,YAAY;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAiBD,wEAAwE;AACxE,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAyCvE"}
@@ -0,0 +1,66 @@
1
+ "use strict";
2
+ var __importDefault = (this && this.__importDefault) || function (mod) {
3
+ return (mod && mod.__esModule) ? mod : { "default": mod };
4
+ };
5
+ Object.defineProperty(exports, "__esModule", { value: true });
6
+ exports.serveCommand = serveCommand;
7
+ const chalk_1 = __importDefault(require("chalk"));
8
+ const child_process_1 = require("child_process");
9
+ const fs_1 = require("fs");
10
+ const path_1 = require("path");
11
+ const specServer_1 = require("../utils/specServer");
12
+ const logger_1 = require("../utils/logger");
13
+ const packageJson = require('../../package.json');
14
+ const DEFAULT_PORT = 4321;
15
+ const DEFAULT_POLL_MS = 1000;
16
+ const MIN_POLL_MS = 250;
17
+ /** Open `url` in the default browser. The URL is built here, never taken from input. */
18
+ function openBrowser(url, logger) {
19
+ const [cmd, args] = process.platform === 'darwin' ? ['open', [url]]
20
+ : process.platform === 'win32' ? ['cmd', ['/c', 'start', '', url]]
21
+ : ['xdg-open', [url]];
22
+ const child = (0, child_process_1.spawn)(cmd, args, { stdio: 'ignore', detached: true });
23
+ child.on('error', () => logger.warn(`Could not open a browser. Open ${url} yourself.`));
24
+ child.unref();
25
+ }
26
+ /** Runs until Ctrl+C; exits the process with 1 on any startup error. */
27
+ async function serveCommand(options) {
28
+ const logger = new logger_1.Logger();
29
+ const root = process.cwd();
30
+ if (!(0, fs_1.existsSync)((0, path_1.join)(root, '.specs'))) {
31
+ logger.error('No .specs/ folder in this directory. Run `specpilot serve` from a project root, or `specpilot init` first.');
32
+ return process.exit(1);
33
+ }
34
+ const port = options.port === undefined ? DEFAULT_PORT : Number(options.port);
35
+ if (!Number.isInteger(port) || port < 1 || port > 65535) {
36
+ logger.error(`Invalid --port "${options.port}". Use a whole number from 1 to 65535.`);
37
+ return process.exit(1);
38
+ }
39
+ const pollMs = options.poll === undefined ? DEFAULT_POLL_MS : Number(options.poll);
40
+ if (!Number.isInteger(pollMs) || pollMs < MIN_POLL_MS) {
41
+ logger.error(`Invalid --poll "${options.poll}". Use a whole number of milliseconds, ${MIN_POLL_MS} or more.`);
42
+ return process.exit(1);
43
+ }
44
+ let handle;
45
+ try {
46
+ handle = await (0, specServer_1.startSpecServer)(root, port, packageJson.version, { pollMs, log: m => logger.warn(m) });
47
+ }
48
+ catch (err) {
49
+ if (err.code === 'EADDRINUSE') {
50
+ logger.error(`Port ${port} is already in use. Pick another with --port, e.g. \`specpilot serve --port ${port === 65535 ? 4322 : port + 1}\`.`);
51
+ }
52
+ else {
53
+ logger.error(`Could not start the server: ${err.message}`);
54
+ }
55
+ return process.exit(1);
56
+ }
57
+ const url = `http://127.0.0.1:${port}`;
58
+ console.log(chalk_1.default.green(`SpecPilot is serving ${root} read-only at ${url}`));
59
+ console.log(chalk_1.default.gray('Open pages update when a spec file changes. Press Ctrl+C to stop.'));
60
+ if (options.open)
61
+ openBrowser(url, logger);
62
+ process.once('SIGINT', () => {
63
+ void handle.close().then(() => process.exit(0));
64
+ });
65
+ }
66
+ //# sourceMappingURL=serve.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"serve.js","sourceRoot":"","sources":["../../src/commands/serve.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,26 @@
1
+ export declare const ALLOWED_FILES: string[];
2
+ export declare const ALLOWED_DIRS: string[];
3
+ /** Upper bound on files one scan returns, so a huge tree cannot make each poll expensive. */
4
+ export declare const MAX_SCAN_FILES = 2000;
5
+ /**
6
+ * Map a requested project-relative path to a real file the server may read, or null.
7
+ * Rejects NUL, backslashes, absolute paths and `..` segments; no folder on the way may be a
8
+ * symlink (the scanner does not follow them either); after resolving a symlinked file the
9
+ * target must still be inside the project root and still inside the allowlist.
10
+ */
11
+ export declare function resolveAllowedPath(root: string, requested: string): string | null;
12
+ export interface AllowedScan {
13
+ /** Project-relative, `/`-joined paths in walk order: the allowlisted files, then each folder sorted. */
14
+ files: string[];
15
+ /** Folders that exist but could not be listed (EACCES, EPERM): their contents are unknown, not gone. */
16
+ unreadable: string[];
17
+ /** True when the scan stopped at `max` files. */
18
+ capped: boolean;
19
+ }
20
+ /**
21
+ * Every path a request may name: the allowlisted files, plus every non-hidden file under the
22
+ * allowlisted folders, skipping `node_modules` and dot-folders such as `.git`. Stops at `max`.
23
+ * Only directory listings are read here, never file content, and nothing here throws.
24
+ */
25
+ export declare function listAllowedFiles(root: string, max?: number): AllowedScan;
26
+ //# sourceMappingURL=specPaths.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"specPaths.d.ts","sourceRoot":"","sources":["../../src/utils/specPaths.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,aAAa,UAAgE,CAAC;AAC3F,eAAO,MAAM,YAAY,UAA0E,CAAC;AAEpG,6FAA6F;AAC7F,eAAO,MAAM,cAAc,OAAO,CAAC;AAYnC;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBjF;AAED,MAAM,WAAW,WAAW;IAC1B,wGAAwG;IACxG,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,wGAAwG;IACxG,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,iDAAiD;IACjD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAiB,GAAG,WAAW,CAsBhF"}
@@ -0,0 +1,92 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.MAX_SCAN_FILES = exports.ALLOWED_DIRS = exports.ALLOWED_FILES = void 0;
4
+ exports.resolveAllowedPath = resolveAllowedPath;
5
+ exports.listAllowedFiles = listAllowedFiles;
6
+ const fs_1 = require("fs");
7
+ const path_1 = require("path");
8
+ // What `specpilot serve` may read (REQ-002.H.4, SEC-004.8), shared by the server and the
9
+ // live-reload poller so both see exactly the same set of files (ARCH-003.16).
10
+ exports.ALLOWED_FILES = ['CLAUDE.md', 'AGENTS.md', '.github/copilot-instructions.md'];
11
+ exports.ALLOWED_DIRS = ['.specs/', '.claude/commands/', '.claude/skills/', '.github/prompts/'];
12
+ /** Upper bound on files one scan returns, so a huge tree cannot make each poll expensive. */
13
+ exports.MAX_SCAN_FILES = 2000;
14
+ /**
15
+ * Allowlisted, and below an allowlisted folder no segment is hidden or `node_modules`: the same
16
+ * rule `listAllowedFiles()` walks by, so what the server serves is exactly what the poller watches.
17
+ */
18
+ function isAllowlisted(rel) {
19
+ if (exports.ALLOWED_FILES.includes(rel))
20
+ return true;
21
+ const dir = exports.ALLOWED_DIRS.find(d => rel.startsWith(d) && rel.length > d.length);
22
+ return !!dir && rel.slice(dir.length).split('/').every(s => s !== '' && !s.startsWith('.') && s !== 'node_modules');
23
+ }
24
+ /**
25
+ * Map a requested project-relative path to a real file the server may read, or null.
26
+ * Rejects NUL, backslashes, absolute paths and `..` segments; no folder on the way may be a
27
+ * symlink (the scanner does not follow them either); after resolving a symlinked file the
28
+ * target must still be inside the project root and still inside the allowlist.
29
+ */
30
+ function resolveAllowedPath(root, requested) {
31
+ if (!requested || requested.includes('\0') || requested.includes('\\'))
32
+ return null;
33
+ if ((0, path_1.isAbsolute)(requested) || path_1.posix.isAbsolute(requested))
34
+ return null;
35
+ if (requested.split('/').includes('..'))
36
+ return null;
37
+ const rel = path_1.posix.normalize(requested);
38
+ if (!isAllowlisted(rel))
39
+ return null;
40
+ try {
41
+ const realRoot = (0, fs_1.realpathSync)(root);
42
+ if ((0, fs_1.realpathSync)((0, path_1.dirname)((0, path_1.join)(root, rel))) !== (0, path_1.join)(realRoot, (0, path_1.dirname)(rel)))
43
+ return null;
44
+ const real = (0, fs_1.realpathSync)((0, path_1.join)(root, rel));
45
+ const back = (0, path_1.relative)(realRoot, real);
46
+ if (!back || back === '..' || back.startsWith('..' + path_1.sep) || (0, path_1.isAbsolute)(back))
47
+ return null;
48
+ if (!isAllowlisted(back.split(path_1.sep).join('/')))
49
+ return null;
50
+ return (0, fs_1.statSync)(real).isFile() ? real : null;
51
+ }
52
+ catch {
53
+ return null;
54
+ }
55
+ }
56
+ /**
57
+ * Every path a request may name: the allowlisted files, plus every non-hidden file under the
58
+ * allowlisted folders, skipping `node_modules` and dot-folders such as `.git`. Stops at `max`.
59
+ * Only directory listings are read here, never file content, and nothing here throws.
60
+ */
61
+ function listAllowedFiles(root, max = exports.MAX_SCAN_FILES) {
62
+ const scan = { files: [...exports.ALLOWED_FILES], unreadable: [], capped: false };
63
+ const walk = (rel) => {
64
+ let entries;
65
+ try {
66
+ entries = (0, fs_1.readdirSync)((0, path_1.join)(root, rel), { withFileTypes: true });
67
+ }
68
+ catch (err) {
69
+ const code = err.code;
70
+ if (code !== 'ENOENT' && code !== 'ENOTDIR')
71
+ scan.unreadable.push(rel);
72
+ return;
73
+ }
74
+ for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))) {
75
+ if (scan.capped)
76
+ return;
77
+ if (e.name.startsWith('.') || e.name === 'node_modules')
78
+ continue;
79
+ const p = `${rel}/${e.name}`;
80
+ if (e.isDirectory())
81
+ walk(p);
82
+ else if (scan.files.length >= max)
83
+ scan.capped = true;
84
+ else
85
+ scan.files.push(p);
86
+ }
87
+ };
88
+ for (const d of exports.ALLOWED_DIRS)
89
+ walk(d.slice(0, -1));
90
+ return scan;
91
+ }
92
+ //# sourceMappingURL=specPaths.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"specPaths.js","sourceRoot":"","sources":["../../src/utils/specPaths.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,22 @@
1
+ export interface PollerOptions {
2
+ /** Idle interval between scans. */
3
+ intervalMs: number;
4
+ /** After a change, re-check this often until a check finds nothing new. */
5
+ settleMs?: number;
6
+ /** Emit anyway once a burst has lasted this long. */
7
+ maxSettleMs?: number;
8
+ /** Called once per settled burst with the changed project-relative paths, sorted. */
9
+ onChange: (paths: string[]) => void;
10
+ /** Where the one-time "scan capped" notice goes. */
11
+ log?: (message: string) => void;
12
+ maxFiles?: number;
13
+ }
14
+ export interface Poller {
15
+ start(): void;
16
+ stop(): void;
17
+ readonly running: boolean;
18
+ }
19
+ /** The paths one scan would watch right now (for tests and diagnostics). */
20
+ export declare function watchedFiles(root: string, maxFiles?: number): string[];
21
+ export declare function createPoller(root: string, opts: PollerOptions): Poller;
22
+ //# sourceMappingURL=specPoller.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"specPoller.d.ts","sourceRoot":"","sources":["../../src/utils/specPoller.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,aAAa;IAC5B,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACpC,oDAAoD;IACpD,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,MAAM;IACrB,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;IACb,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B;AAwBD,4EAA4E;AAC5E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,SAAiB,GAAG,MAAM,EAAE,CAE9E;AAYD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAiEtE"}
@@ -0,0 +1,119 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.watchedFiles = watchedFiles;
4
+ exports.createPoller = createPoller;
5
+ const fs_1 = require("fs");
6
+ const path_1 = require("path");
7
+ const specPaths_1 = require("./specPaths");
8
+ /** stat() every allowlisted file. ENOENT (gone since readdir) → absent; EACCES or any other error → keep what we knew. */
9
+ function scan(root, prev, maxFiles) {
10
+ const { files, unreadable, capped } = (0, specPaths_1.listAllowedFiles)(root, maxFiles);
11
+ const snap = new Map();
12
+ for (const path of files) {
13
+ try {
14
+ const st = (0, fs_1.statSync)((0, path_1.join)(root, path));
15
+ // Only what the server would actually serve (regular file, symlinks resolved inside the allowlist).
16
+ if (st.isFile() && (0, specPaths_1.resolveAllowedPath)(root, path))
17
+ snap.set(path, { mtimeMs: st.mtimeMs, size: st.size, ino: st.ino });
18
+ }
19
+ catch (err) {
20
+ if (err.code === 'ENOENT')
21
+ continue;
22
+ const known = prev.get(path);
23
+ if (known)
24
+ snap.set(path, known);
25
+ }
26
+ }
27
+ // A folder we could not list: its files are unknown this time, not deleted.
28
+ for (const dir of unreadable) {
29
+ for (const [path, entry] of prev)
30
+ if (path.startsWith(dir + '/') && !snap.has(path))
31
+ snap.set(path, entry);
32
+ }
33
+ return { snap, capped };
34
+ }
35
+ /** The paths one scan would watch right now (for tests and diagnostics). */
36
+ function watchedFiles(root, maxFiles = specPaths_1.MAX_SCAN_FILES) {
37
+ return [...scan(root, new Map(), maxFiles).snap.keys()].sort();
38
+ }
39
+ function diff(a, b) {
40
+ const changed = new Set();
41
+ for (const [path, x] of a) {
42
+ const y = b.get(path);
43
+ if (!y || y.mtimeMs !== x.mtimeMs || y.size !== x.size || y.ino !== x.ino)
44
+ changed.add(path);
45
+ }
46
+ for (const path of b.keys())
47
+ if (!a.has(path))
48
+ changed.add(path);
49
+ return [...changed].sort();
50
+ }
51
+ function createPoller(root, opts) {
52
+ const settleMs = opts.settleMs ?? 150;
53
+ const maxSettleMs = opts.maxSettleMs ?? 2000;
54
+ const maxFiles = opts.maxFiles ?? specPaths_1.MAX_SCAN_FILES;
55
+ let timer = null;
56
+ let prev = new Map();
57
+ let pending = new Set();
58
+ let burstStart = 0;
59
+ let warnedCap = false;
60
+ const check = () => {
61
+ const { snap, capped } = scan(root, prev, maxFiles);
62
+ if (capped && !warnedCap) {
63
+ warnedCap = true;
64
+ opts.log?.(`specpilot serve: watching the first ${maxFiles} files only; changes to the rest are not detected.`);
65
+ }
66
+ const changed = diff(prev, snap);
67
+ prev = snap;
68
+ return changed;
69
+ };
70
+ const tick = () => {
71
+ timer = null;
72
+ let changed = [];
73
+ try {
74
+ changed = check();
75
+ }
76
+ catch {
77
+ // Nothing in a scan should throw; if something does, keep polling rather than die.
78
+ }
79
+ changed.forEach(p => pending.add(p));
80
+ const settling = pending.size > 0;
81
+ if (settling && !burstStart)
82
+ burstStart = Date.now();
83
+ if (settling && changed.length && Date.now() - burstStart < maxSettleMs) {
84
+ timer = setTimeout(tick, settleMs);
85
+ return;
86
+ }
87
+ if (settling) {
88
+ const paths = [...pending].sort();
89
+ pending = new Set();
90
+ burstStart = 0;
91
+ opts.onChange(paths);
92
+ }
93
+ if (poller.running)
94
+ timer = setTimeout(tick, opts.intervalMs);
95
+ };
96
+ let active = false;
97
+ const poller = {
98
+ start() {
99
+ if (active)
100
+ return;
101
+ active = true;
102
+ prev = scan(root, new Map(), maxFiles).snap;
103
+ timer = setTimeout(tick, opts.intervalMs);
104
+ },
105
+ stop() {
106
+ active = false;
107
+ if (timer)
108
+ clearTimeout(timer);
109
+ timer = null;
110
+ pending = new Set();
111
+ burstStart = 0;
112
+ },
113
+ get running() {
114
+ return active;
115
+ },
116
+ };
117
+ return poller;
118
+ }
119
+ //# sourceMappingURL=specPoller.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"specPoller.js","sourceRoot":"","sources":["../../src/utils/specPoller.ts"],"names":[],"mappings":";;AA4DA,oCAEC;AAYD,oCAiEC;AA3ID,2BAA8B;AAC9B,+BAA4B;AAC5B,2CAAmF;AAmCnF,0HAA0H;AAC1H,SAAS,IAAI,CAAC,IAAY,EAAE,IAAc,EAAE,QAAgB;IAC1D,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,IAAA,4BAAgB,EAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvE,MAAM,IAAI,GAAa,IAAI,GAAG,EAAE,CAAC;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,EAAE,GAAG,IAAA,aAAQ,EAAC,IAAA,WAAI,EAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;YACtC,oGAAoG;YACpG,IAAI,EAAE,CAAC,MAAM,EAAE,IAAI,IAAA,8BAAkB,EAAC,IAAI,EAAE,IAAI,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC;QACzH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ;gBAAE,SAAS;YAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAC7B,IAAI,KAAK;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IACD,4EAA4E;IAC5E,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;QAC7B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI;YAAE,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAC7G,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC1B,CAAC;AAED,4EAA4E;AAC5E,SAAgB,YAAY,CAAC,IAAY,EAAE,QAAQ,GAAG,0BAAc;IAClE,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACjE,CAAC;AAED,SAAS,IAAI,CAAC,CAAW,EAAE,CAAW;IACpC,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,KAAK,CAAC,CAAC,OAAO,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC/F,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE;QAAE,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED,SAAgB,YAAY,CAAC,IAAY,EAAE,IAAmB;IAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,GAAG,CAAC;IACtC,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,0BAAc,CAAC;IACjD,IAAI,KAAK,GAA0B,IAAI,CAAC;IACxC,IAAI,IAAI,GAAa,IAAI,GAAG,EAAE,CAAC;IAC/B,IAAI,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAChC,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,SAAS,GAAG,KAAK,CAAC;IAEtB,MAAM,KAAK,GAAG,GAAa,EAAE;QAC3B,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpD,IAAI,MAAM,IAAI,CAAC,SAAS,EAAE,CAAC;YACzB,SAAS,GAAG,IAAI,CAAC;YACjB,IAAI,CAAC,GAAG,EAAE,CAAC,uCAAuC,QAAQ,oDAAoD,CAAC,CAAC;QAClH,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QACjC,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO,OAAO,CAAC;IACjB,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG,GAAS,EAAE;QACtB,KAAK,GAAG,IAAI,CAAC;QACb,IAAI,OAAO,GAAa,EAAE,CAAC;QAC3B,IAAI,CAAC;YACH,OAAO,GAAG,KAAK,EAAE,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,mFAAmF;QACrF,CAAC;QACD,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC;QAClC,IAAI,QAAQ,IAAI,CAAC,UAAU;YAAE,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrD,IAAI,QAAQ,IAAI,OAAO,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,UAAU,GAAG,WAAW,EAAE,CAAC;YACxE,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YACnC,OAAO;QACT,CAAC;QACD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,KAAK,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YAClC,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;YACpB,UAAU,GAAG,CAAC,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACvB,CAAC;QACD,IAAI,MAAM,CAAC,OAAO;YAAE,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;IAChE,CAAC,CAAC;IAEF,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,MAAM,GAAW;QACrB,KAAK;YACH,IAAI,MAAM;gBAAE,OAAO;YACnB,MAAM,GAAG,IAAI,CAAC;YACd,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,EAAE,EAAE,QAAQ,CAAC,CAAC,IAAI,CAAC;YAC5C,KAAK,GAAG,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;QAC5C,CAAC;QACD,IAAI;YACF,MAAM,GAAG,KAAK,CAAC;YACf,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;YAC/B,KAAK,GAAG,IAAI,CAAC;YACb,OAAO,GAAG,IAAI,GAAG,EAAE,CAAC;YACpB,UAAU,GAAG,CAAC,CAAC;QACjB,CAAC;QACD,IAAI,OAAO;YACT,OAAO,MAAM,CAAC;QAChB,CAAC;KACF,CAAC;IACF,OAAO,MAAM,CAAC;AAChB,CAAC"}
@@ -0,0 +1,60 @@
1
+ import { Server } from 'http';
2
+ /** DNS-rebinding guard: only the loopback names this server was reached on. */
3
+ export declare function isAllowedHost(host: string | undefined, port: number): boolean;
4
+ /** Current branch from .git/HEAD (worktree `.git` files and detached HEADs included), or null. */
5
+ export declare function readBranch(root: string): string | null;
6
+ export interface NavFile {
7
+ path: string;
8
+ frontMatter: Record<string, string> | null;
9
+ }
10
+ /** Everything `GET /api/specs` returns: project metadata, readSpecs() output, the nav tree. */
11
+ export declare function buildSpecsPayload(root: string, specpilotVersion: string): {
12
+ project: {
13
+ name: string | null;
14
+ root: string;
15
+ branch: string | null;
16
+ specpilotVersion: string;
17
+ };
18
+ files: Record<string, import("./specReader").SpecMeta>;
19
+ tasks: {
20
+ intro: string;
21
+ backlog: import("./specReader").TaskRow[];
22
+ currentSprint: import("./specReader").TaskRow[];
23
+ completed: import("./specReader").CompletedRow[];
24
+ malformed: string[];
25
+ } | null;
26
+ nav: {
27
+ specs: string[];
28
+ instructions: {
29
+ path: string;
30
+ exists: boolean;
31
+ bytes: number;
32
+ }[];
33
+ commands: NavFile[];
34
+ skills: NavFile[];
35
+ prompts: NavFile[];
36
+ };
37
+ };
38
+ /** Most `/api/events` streams open at once; the next one gets 503 (SEC-004.9). */
39
+ export declare const MAX_EVENT_STREAMS = 8;
40
+ export interface SpecServerOptions {
41
+ /** Change-detection interval in ms (`--poll`). */
42
+ pollMs?: number;
43
+ /** Heartbeat comment interval for event streams. */
44
+ heartbeatMs?: number;
45
+ /** Poller settle interval after a change (tests shorten it). */
46
+ settleMs?: number;
47
+ /** One-time notices, e.g. the scan cap. */
48
+ log?: (message: string) => void;
49
+ }
50
+ export interface SpecServer {
51
+ server: Server;
52
+ /** Open event streams right now. */
53
+ streams(): number;
54
+ /** End every event stream, clear every timer, then close the listener. */
55
+ close(): Promise<void>;
56
+ }
57
+ export declare function createSpecServer(root: string, specpilotVersion: string, opts?: SpecServerOptions): SpecServer;
58
+ /** Listen on 127.0.0.1 only. Rejects with the listen error (e.g. EADDRINUSE). */
59
+ export declare function startSpecServer(root: string, port: number, specpilotVersion: string, opts?: SpecServerOptions): Promise<SpecServer>;
60
+ //# sourceMappingURL=specServer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"specServer.d.ts","sourceRoot":"","sources":["../../src/utils/specServer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,MAAM,EAAkB,MAAM,MAAM,CAAC;AAwB7E,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAG7E;AAED,kGAAkG;AAClG,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAetD;AAgBD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI,CAAC;CAC5C;AA+BD,+FAA+F;AAC/F,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;EA4BvE;AAeD,kFAAkF;AAClF,eAAO,MAAM,iBAAiB,IAAI,CAAC;AAEnC,MAAM,WAAW,iBAAiB;IAChC,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,OAAO,IAAI,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,UAAU,CAoEjH;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,UAAU,CAAC,CASvI"}