tslaws 0.4.0 → 0.5.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 +10 -2
- package/dist/cli.d.ts +12 -0
- package/dist/cli.js +96 -27
- package/dist/delegation.d.ts +68 -0
- package/dist/delegation.js +199 -0
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -166,7 +166,7 @@ See [docs/laws.md](../../docs/laws.md#the-dashboard).
|
|
|
166
166
|
|
|
167
167
|
`tsc-laws.lock` holds a hash of every law declaration and the list of coverage exemptions. A change, an added law, a removed
|
|
168
168
|
law or a new `@tslaws-exempt` fails the check until a person runs `tslaws accept`, which refuses to run without a terminal,
|
|
169
|
-
under `CI`, or with `TSLAWS_AGENT` set
|
|
169
|
+
under `CI`, or with `TSLAWS_AGENT` set, unless a person has lent it for a limited time with `tslaws delegate grant`. Agents propose laws in `*.proposed.laws.ts` and try them with `tslaws check
|
|
170
170
|
--proposed` (no lock, no coverage gate); a person moves them into a `*.laws.ts` file and accepts.
|
|
171
171
|
|
|
172
172
|
`hooks/claude-hook.mjs` is a Claude Code hook that blocks `git commit` and sends an agent back to work when the check fails;
|
|
@@ -177,6 +177,9 @@ under `CI`, or with `TSLAWS_AGENT` set. Agents propose laws in `*.proposed.laws.
|
|
|
177
177
|
```
|
|
178
178
|
tslaws init [--force]
|
|
179
179
|
tslaws accept [files...]
|
|
180
|
+
tslaws delegate grant [--for 1h|8h|1d|7d] [--root DIR]
|
|
181
|
+
tslaws delegate revoke [--root DIR]
|
|
182
|
+
tslaws delegate status
|
|
180
183
|
tslaws check [files...] [--json] [--summary] [--watch] [--runs N] [--seed N] [--no-prove] [--bound N]
|
|
181
184
|
[--proof-timeout MS] [--property-timeout MS] [--proposed] [--compiler PATH]
|
|
182
185
|
```
|
|
@@ -184,7 +187,12 @@ tslaws check [files...] [--json] [--summary] [--watch] [--runs N] [--seed N] [--
|
|
|
184
187
|
- `init` scaffolds `tslaws.json`, the `.tslaws` ignore entry, the agent rules in `AGENTS.md`, the Claude Code hook in
|
|
185
188
|
`.claude/settings.json`, and a starter law if none exists. It never writes the lock; a person then runs `accept`.
|
|
186
189
|
- `accept` records the laws and the `@tslaws-exempt` functions in `tsc-laws.lock`. It refuses to run without a terminal,
|
|
187
|
-
under `CI`, or with `TSLAWS_AGENT` set.
|
|
190
|
+
under `CI`, or with `TSLAWS_AGENT` set, unless a live delegation covers the project (never under `CI`).
|
|
191
|
+
- `delegate grant` lends `accept` to agents for 1h, 8h (default), 1d or 7d (the most), for one project root. `delegate revoke`
|
|
192
|
+
withdraws it and `delegate status` lists grants; `grant` and `revoke` need a terminal and refuse under `CI` or
|
|
193
|
+
`TSLAWS_AGENT`. The grant lives in `~/.tslaws/delegation.json`, outside the repository (found through the operating
|
|
194
|
+
system's user record, not `HOME`; an agent running as the same user can still write that file). A delegated `accept` appends to `.tslaws/accept.log` and prints `DELEGATED ACCEPT`.
|
|
195
|
+
A grant is a person's decision, bounded in time, outside the repo, audited in `accept.log`. See [docs/laws.md](../../docs/laws.md#lending-accept-to-an-agent).
|
|
188
196
|
- `check` exits 0 only when every law is `proved`, `bounded` or `tested`, nothing is `uncovered`, the files compile and the
|
|
189
197
|
lock matches. `--json` adds a `hint` to each result, the concrete next action for an agent. `--summary` prints only the
|
|
190
198
|
results that do not pass, plus the totals. `--watch` re-runs on every `.ts` change.
|
package/dist/cli.d.ts
CHANGED
|
@@ -1 +1,13 @@
|
|
|
1
|
+
/** What a command needs from its caller. `home` is for unit tests; the CLI never sets it. */
|
|
2
|
+
export interface CommandContext {
|
|
3
|
+
isTTY: boolean;
|
|
4
|
+
env: NodeJS.ProcessEnv;
|
|
5
|
+
home?: string;
|
|
6
|
+
now?: Date;
|
|
7
|
+
out?: (text: string) => void;
|
|
8
|
+
err?: (text: string) => void;
|
|
9
|
+
}
|
|
10
|
+
export declare function acceptCommand(cwd: string, flags: Map<string, string | true>, files: string[], ctx: CommandContext): Promise<number>;
|
|
11
|
+
/** `tslaws delegate <action> [--for D] [--root DIR]`; `argv` is everything after `delegate`. */
|
|
12
|
+
export declare function runDelegateCommand(argv: string[], cwd: string, ctx: CommandContext): number;
|
|
1
13
|
export declare function main(args: string[]): Promise<number>;
|
package/dist/cli.js
CHANGED
|
@@ -15,13 +15,17 @@ import { readConfig } from "./coverage.js";
|
|
|
15
15
|
import { mutate, renderMutation } from "./mutate.js";
|
|
16
16
|
import { mutateDefaults, resolveSettings } from "./settings.js";
|
|
17
17
|
import { serveUi } from "./ui.js";
|
|
18
|
+
import { acceptGate, defaultDuration, describeGrants, fileHash, grantFor, logDelegatedAccept, parseDuration, personOnly, revokeFor, } from "./delegation.js";
|
|
18
19
|
import { writeLock } from "./lock.js";
|
|
19
20
|
const usage = `tslaws init [--force] scaffold tslaws.json, .gitignore, AGENTS.md, Claude Code hooks and a starter law (never writes the lock)
|
|
20
21
|
tslaws check [files...] [--reporter text|json|junit|github] [--json] [--summary] [--watch] [--runs N] [--seed N] [--no-prove] [--no-regressions] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--proposed] [--compiler PATH] [--browser chromium|firefox|webkit]
|
|
21
22
|
tslaws ui [files...] [--port N] [--no-open] [--tab] open a dashboard of the laws in its own desktop window (--tab: a browser tab): tree, filters, search, source, live reruns on save
|
|
22
23
|
tslaws mutate [files...] [--max N] [--seed N] [--runs N] [--bound N] [--proof-timeout MS] [--property-timeout MS] [--browser ENGINE] [--json] mutation-test the laws: mutate covered code, report mutants no law kills
|
|
23
24
|
tslaws regressions [list|clear] show or delete the stored counterexamples (.tslaws/regressions); check replays them first, --no-regressions skips them
|
|
24
|
-
tslaws accept [files...] record the current laws in tsc-laws.lock (people only: needs a terminal)
|
|
25
|
+
tslaws accept [files...] record the current laws in tsc-laws.lock (people only: needs a terminal, or a live delegation; never under CI)
|
|
26
|
+
tslaws delegate grant [--for 1h|8h|1d|7d] [--root DIR] lend accept to an agent for a limited time (people only; default 8h, max 7d)
|
|
27
|
+
tslaws delegate revoke [--root DIR] withdraw the delegation for a project (people only)
|
|
28
|
+
tslaws delegate status list delegations and when they end
|
|
25
29
|
tslaws promote [file] [--all] move proposed laws (*.proposed.laws.ts) into the accepted *.laws.ts, asking per law (people only: needs a terminal; run accept afterwards)
|
|
26
30
|
tslaws mcp [--compiler PATH] serve check, check_proposed, explain and propose as Model Context Protocol tools on stdio (cannot accept or touch the lock)
|
|
27
31
|
|
|
@@ -65,6 +69,8 @@ function parse(args) {
|
|
|
65
69
|
'port',
|
|
66
70
|
'reporter',
|
|
67
71
|
'max',
|
|
72
|
+
'for',
|
|
73
|
+
'root',
|
|
68
74
|
]);
|
|
69
75
|
for (let i = 0; i < args.length; i += 1) {
|
|
70
76
|
const arg = args[i];
|
|
@@ -83,7 +89,8 @@ function parse(args) {
|
|
|
83
89
|
arg === 'mutate' ||
|
|
84
90
|
arg === 'regressions' ||
|
|
85
91
|
arg === 'mcp' ||
|
|
86
|
-
arg === 'promote'
|
|
92
|
+
arg === 'promote' ||
|
|
93
|
+
arg === 'delegate'))
|
|
87
94
|
command = arg;
|
|
88
95
|
else
|
|
89
96
|
files.push(arg);
|
|
@@ -229,6 +236,89 @@ async function watchChecks(cwd, flags, files) {
|
|
|
229
236
|
});
|
|
230
237
|
});
|
|
231
238
|
}
|
|
239
|
+
const stdoutWrite = (text) => void process.stdout.write(text);
|
|
240
|
+
const stderrWrite = (text) => void process.stderr.write(text);
|
|
241
|
+
export async function acceptCommand(cwd, flags, files, ctx) {
|
|
242
|
+
const out = ctx.out ?? stdoutWrite;
|
|
243
|
+
const err = ctx.err ?? stderrWrite;
|
|
244
|
+
const chosen = lawFiles(cwd, flags, files);
|
|
245
|
+
if (chosen.length === 0) {
|
|
246
|
+
err('no laws files found (looking for *.laws.ts)\n');
|
|
247
|
+
return 1;
|
|
248
|
+
}
|
|
249
|
+
const gate = acceptGate({ isTTY: ctx.isTTY, env: ctx.env, root: cwd, now: ctx.now, home: ctx.home });
|
|
250
|
+
if (!gate.ok) {
|
|
251
|
+
err(`${gate.message}\n`);
|
|
252
|
+
return 1;
|
|
253
|
+
}
|
|
254
|
+
const opts = options(cwd, flags, chosen);
|
|
255
|
+
const laws = readManifest(opts.compiler, opts.files, cwd);
|
|
256
|
+
out(`${laws.length} laws in ${chosen.length} files:\n${laws.map((l) => ` ${l.file}:${l.line} ${l.name}`).join('\n')}\n`);
|
|
257
|
+
if (!gate.delegated) {
|
|
258
|
+
const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
259
|
+
const answer = await rl.question('Type ACCEPT to write tsc-laws.lock: ');
|
|
260
|
+
rl.close();
|
|
261
|
+
if (answer.trim() !== 'ACCEPT')
|
|
262
|
+
return 1;
|
|
263
|
+
}
|
|
264
|
+
const before = fileHash(opts.lockFile);
|
|
265
|
+
const exempt = exemptionsOf(opts);
|
|
266
|
+
if (exempt.length > 0)
|
|
267
|
+
out(`exempt from coverage:\n${exempt.map((e) => ` ${e}`).join('\n')}\n`);
|
|
268
|
+
writeLock(opts.lockFile, laws, exempt);
|
|
269
|
+
out('tsc-laws.lock written\n');
|
|
270
|
+
if (gate.delegated) {
|
|
271
|
+
logDelegatedAccept(cwd, gate.grant, before, fileHash(opts.lockFile), ctx.now ?? new Date());
|
|
272
|
+
out(`DELEGATED ACCEPT: a person lent this act until ${gate.grant.expires}; recorded in .tslaws/accept.log\n`);
|
|
273
|
+
}
|
|
274
|
+
return 0;
|
|
275
|
+
}
|
|
276
|
+
/** `tslaws delegate <action> [--for D] [--root DIR]`; `argv` is everything after `delegate`. */
|
|
277
|
+
export function runDelegateCommand(argv, cwd, ctx) {
|
|
278
|
+
const { flags, files } = parse(['delegate', ...argv]);
|
|
279
|
+
return delegateCommand(cwd, files[0], flags, ctx);
|
|
280
|
+
}
|
|
281
|
+
function delegateCommand(cwd, action, flags, ctx) {
|
|
282
|
+
const out = ctx.out ?? stdoutWrite;
|
|
283
|
+
const err = ctx.err ?? stderrWrite;
|
|
284
|
+
const now = ctx.now ?? new Date();
|
|
285
|
+
if (action === 'status') {
|
|
286
|
+
out(`${describeGrants(now, ctx.home).join('\n')}\n`);
|
|
287
|
+
return 0;
|
|
288
|
+
}
|
|
289
|
+
if (action !== 'grant' && action !== 'revoke') {
|
|
290
|
+
err('usage: tslaws delegate grant|revoke|status\n');
|
|
291
|
+
return 1;
|
|
292
|
+
}
|
|
293
|
+
if (!personOnly({ isTTY: ctx.isTTY, env: ctx.env })) {
|
|
294
|
+
err(`delegate ${action} is a person's decision and needs a terminal; it will not run here\n`);
|
|
295
|
+
return 1;
|
|
296
|
+
}
|
|
297
|
+
const rootFlag = flags.get('root');
|
|
298
|
+
const target = rootFlag === undefined || rootFlag === true ? cwd : resolve(cwd, rootFlag);
|
|
299
|
+
if (action === 'revoke') {
|
|
300
|
+
const removed = revokeFor(target, ctx.home);
|
|
301
|
+
if (typeof removed === 'string') {
|
|
302
|
+
err(`${removed}\n`);
|
|
303
|
+
return 1;
|
|
304
|
+
}
|
|
305
|
+
out(`${removed} delegation${removed === 1 ? '' : 's'} revoked\n`);
|
|
306
|
+
return 0;
|
|
307
|
+
}
|
|
308
|
+
const lengthFlag = flags.get('for');
|
|
309
|
+
const ms = parseDuration(lengthFlag === undefined ? defaultDuration : String(lengthFlag));
|
|
310
|
+
if (ms === undefined) {
|
|
311
|
+
err('--for takes 1h, 8h, 1d or 7d (the most is 7d)\n');
|
|
312
|
+
return 1;
|
|
313
|
+
}
|
|
314
|
+
const granted = grantFor(target, ms, now, ctx.home);
|
|
315
|
+
if (typeof granted === 'string') {
|
|
316
|
+
err(`${granted}\n`);
|
|
317
|
+
return 1;
|
|
318
|
+
}
|
|
319
|
+
out(`accept is lent to agents for ${granted.root} until ${granted.expires}\n`);
|
|
320
|
+
return 0;
|
|
321
|
+
}
|
|
232
322
|
export async function main(args) {
|
|
233
323
|
if (args.includes('--help') || args.includes('-h')) {
|
|
234
324
|
process.stdout.write(`${usage}\n`);
|
|
@@ -240,31 +330,10 @@ export async function main(args) {
|
|
|
240
330
|
process.stdout.write(`${init({ cwd, force: flags.has('force') }).join('\n')}\n\n${nextStep}\n`);
|
|
241
331
|
return 0;
|
|
242
332
|
}
|
|
243
|
-
if (command === 'accept')
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
return 1;
|
|
248
|
-
}
|
|
249
|
-
if (!process.stdin.isTTY || process.env.TSLAWS_AGENT !== undefined || process.env.CI !== undefined) {
|
|
250
|
-
process.stderr.write('accept records laws as correct and needs a person at a terminal; it will not run here\n');
|
|
251
|
-
return 1;
|
|
252
|
-
}
|
|
253
|
-
const opts = options(cwd, flags, chosen);
|
|
254
|
-
const laws = readManifest(opts.compiler, opts.files, cwd);
|
|
255
|
-
process.stdout.write(`${laws.length} laws in ${chosen.length} files:\n${laws.map((l) => ` ${l.file}:${l.line} ${l.name}`).join('\n')}\n`);
|
|
256
|
-
const rl = createInterface({ input: process.stdin, output: process.stdout });
|
|
257
|
-
const answer = await rl.question('Type ACCEPT to write tsc-laws.lock: ');
|
|
258
|
-
rl.close();
|
|
259
|
-
if (answer.trim() !== 'ACCEPT')
|
|
260
|
-
return 1;
|
|
261
|
-
const exempt = exemptionsOf(opts);
|
|
262
|
-
if (exempt.length > 0)
|
|
263
|
-
process.stdout.write(`exempt from coverage:\n${exempt.map((e) => ` ${e}`).join('\n')}\n`);
|
|
264
|
-
writeLock(opts.lockFile, laws, exempt);
|
|
265
|
-
process.stdout.write('tsc-laws.lock written\n');
|
|
266
|
-
return 0;
|
|
267
|
-
}
|
|
333
|
+
if (command === 'accept')
|
|
334
|
+
return acceptCommand(cwd, flags, files, { isTTY: process.stdin.isTTY === true, env: process.env });
|
|
335
|
+
if (command === 'delegate')
|
|
336
|
+
return delegateCommand(cwd, files[0], flags, { isTTY: process.stdin.isTTY === true, env: process.env });
|
|
268
337
|
if (command === 'mcp')
|
|
269
338
|
return serveMcp({ cwd, compiler: options(cwd, flags, []).compiler });
|
|
270
339
|
if (command === 'promote') {
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
export interface Grant {
|
|
2
|
+
root: string;
|
|
3
|
+
expires: string;
|
|
4
|
+
note?: string;
|
|
5
|
+
}
|
|
6
|
+
export declare const defaultDuration = "8h";
|
|
7
|
+
/**
|
|
8
|
+
* The person's home directory from the operating system's user record (getpwuid on POSIX, the profile directory of the
|
|
9
|
+
* user token on Windows). HOME and USERPROFILE are ignored on purpose. An empty string means it cannot be found.
|
|
10
|
+
*/
|
|
11
|
+
export declare function userHome(): string;
|
|
12
|
+
/** The grants file under a home directory: the real one by default, a temp directory in unit tests. */
|
|
13
|
+
export declare function delegationFile(home?: string): string;
|
|
14
|
+
export declare function parseDuration(text: string): number | undefined;
|
|
15
|
+
/** The real path of a directory; undefined when it is missing. */
|
|
16
|
+
export declare function realRoot(dir: string): string | undefined;
|
|
17
|
+
export type Grants = {
|
|
18
|
+
ok: true;
|
|
19
|
+
grants: Grant[];
|
|
20
|
+
} | {
|
|
21
|
+
ok: false;
|
|
22
|
+
reason: string;
|
|
23
|
+
};
|
|
24
|
+
/** Reads the grants. A missing file is an empty list; an unsafe or malformed one is an error. */
|
|
25
|
+
export declare function readGrants(home?: string): Grants;
|
|
26
|
+
export type Verdict = {
|
|
27
|
+
ok: true;
|
|
28
|
+
grant: Grant;
|
|
29
|
+
} | {
|
|
30
|
+
ok: false;
|
|
31
|
+
reason: string;
|
|
32
|
+
};
|
|
33
|
+
/** The live grant for a project root. Real paths are compared, and a grant naming a symlink never matches. */
|
|
34
|
+
export declare function findGrant(root: string, now: Date, home?: string): Verdict;
|
|
35
|
+
export interface GateInput {
|
|
36
|
+
isTTY: boolean;
|
|
37
|
+
env: NodeJS.ProcessEnv;
|
|
38
|
+
root: string;
|
|
39
|
+
now?: Date;
|
|
40
|
+
/** Home directory holding the grants; unit tests pass a temp directory. */
|
|
41
|
+
home?: string;
|
|
42
|
+
}
|
|
43
|
+
export type Gate = {
|
|
44
|
+
ok: true;
|
|
45
|
+
delegated: false;
|
|
46
|
+
} | {
|
|
47
|
+
ok: true;
|
|
48
|
+
delegated: true;
|
|
49
|
+
grant: Grant;
|
|
50
|
+
} | {
|
|
51
|
+
ok: false;
|
|
52
|
+
message: string;
|
|
53
|
+
};
|
|
54
|
+
/** Decides whether `accept` may run: a person at a terminal, else a live grant. CI never. */
|
|
55
|
+
export declare function acceptGate(input: GateInput): Gate;
|
|
56
|
+
/** The gate for acts only a person may do: a terminal, no agent marker, no CI. */
|
|
57
|
+
export declare function personOnly(input: {
|
|
58
|
+
isTTY: boolean;
|
|
59
|
+
env: NodeJS.ProcessEnv;
|
|
60
|
+
}): boolean;
|
|
61
|
+
/** Records a grant for a project; returns it, or the reason it was refused. */
|
|
62
|
+
export declare function grantFor(root: string, ms: number, now: Date, home?: string): Grant | string;
|
|
63
|
+
/** Removes the grants for a project; returns how many, or the reason it was refused. */
|
|
64
|
+
export declare function revokeFor(root: string, home?: string): number | string;
|
|
65
|
+
export declare function describeGrants(now: Date, home?: string): string[];
|
|
66
|
+
export declare function fileHash(path: string): string;
|
|
67
|
+
/** Appends the audit line for a delegated accept to `<project>/.tslaws/accept.log`. */
|
|
68
|
+
export declare function logDelegatedAccept(root: string, grant: Grant, before: string, after: string, now: Date): void;
|
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
// A person's time-limited delegation of `tslaws accept` to an agent. The grant lives in the person's home
|
|
2
|
+
// directory, outside every project, so nothing an agent can edit in a repository can create one.
|
|
3
|
+
import { createHash } from 'node:crypto';
|
|
4
|
+
import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, writeFileSync, } from 'node:fs';
|
|
5
|
+
import { userInfo } from 'node:os';
|
|
6
|
+
import { join, resolve, sep } from 'node:path';
|
|
7
|
+
export const defaultDuration = '8h';
|
|
8
|
+
const hour = 3_600_000;
|
|
9
|
+
const durations = { '1h': hour, '8h': 8 * hour, '1d': 24 * hour, '7d': 168 * hour };
|
|
10
|
+
const regrant = 'run `tslaws delegate grant` at a terminal to lend accept for a limited time';
|
|
11
|
+
/**
|
|
12
|
+
* The person's home directory from the operating system's user record (getpwuid on POSIX, the profile directory of the
|
|
13
|
+
* user token on Windows). HOME and USERPROFILE are ignored on purpose. An empty string means it cannot be found.
|
|
14
|
+
*/
|
|
15
|
+
export function userHome() {
|
|
16
|
+
try {
|
|
17
|
+
return userInfo().homedir;
|
|
18
|
+
}
|
|
19
|
+
catch {
|
|
20
|
+
return '';
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
/** The grants file under a home directory: the real one by default, a temp directory in unit tests. */
|
|
24
|
+
export function delegationFile(home = userHome()) {
|
|
25
|
+
return join(home, '.tslaws', 'delegation.json');
|
|
26
|
+
}
|
|
27
|
+
export function parseDuration(text) {
|
|
28
|
+
return Object.hasOwn(durations, text) ? durations[text] : undefined;
|
|
29
|
+
}
|
|
30
|
+
/** The real path of a directory; undefined when it is missing. */
|
|
31
|
+
export function realRoot(dir) {
|
|
32
|
+
try {
|
|
33
|
+
return realpathSync.native(resolve(dir));
|
|
34
|
+
}
|
|
35
|
+
catch {
|
|
36
|
+
return undefined;
|
|
37
|
+
}
|
|
38
|
+
}
|
|
39
|
+
function same(a, b) {
|
|
40
|
+
return process.platform === 'win32' || process.platform === 'darwin' ? a.toLowerCase() === b.toLowerCase() : a === b;
|
|
41
|
+
}
|
|
42
|
+
/** The grants directory must resolve inside the real home directory, not through a symlink elsewhere. */
|
|
43
|
+
function grantsDirProblem(home) {
|
|
44
|
+
if (home === '')
|
|
45
|
+
return 'the home directory is unknown (the user database gave none)';
|
|
46
|
+
const dir = join(home, '.tslaws');
|
|
47
|
+
if (!existsSync(dir))
|
|
48
|
+
return undefined;
|
|
49
|
+
const base = realRoot(home);
|
|
50
|
+
const real = realRoot(dir);
|
|
51
|
+
if (base === undefined || real === undefined)
|
|
52
|
+
return `${dir} cannot be resolved`;
|
|
53
|
+
const inside = real.length > base.length && same(real.slice(0, base.length), base) && real[base.length] === sep;
|
|
54
|
+
return inside ? undefined : `${dir} resolves outside the home directory (${real})`;
|
|
55
|
+
}
|
|
56
|
+
/** A home directory that is the project root, or inside it, is project-controlled and never a trust root. */
|
|
57
|
+
function homeInsideRoot(home, root) {
|
|
58
|
+
const h = home === '' ? undefined : realRoot(home);
|
|
59
|
+
if (h === undefined)
|
|
60
|
+
return undefined;
|
|
61
|
+
const inside = same(h, root) || (h.length > root.length && same(h.slice(0, root.length), root) && h[root.length] === sep);
|
|
62
|
+
return inside ? `the home directory ${h} is inside the project root` : undefined;
|
|
63
|
+
}
|
|
64
|
+
function isGrant(value) {
|
|
65
|
+
if (typeof value !== 'object' || value === null)
|
|
66
|
+
return false;
|
|
67
|
+
const g = value;
|
|
68
|
+
return (typeof g.root === 'string' &&
|
|
69
|
+
typeof g.expires === 'string' &&
|
|
70
|
+
Number.isFinite(Date.parse(g.expires)) &&
|
|
71
|
+
(g.note === undefined || typeof g.note === 'string'));
|
|
72
|
+
}
|
|
73
|
+
/** Reads the grants. A missing file is an empty list; an unsafe or malformed one is an error. */
|
|
74
|
+
export function readGrants(home = userHome()) {
|
|
75
|
+
const file = delegationFile(home);
|
|
76
|
+
const place = grantsDirProblem(home);
|
|
77
|
+
if (place !== undefined)
|
|
78
|
+
return { ok: false, reason: place };
|
|
79
|
+
if (!existsSync(file))
|
|
80
|
+
return { ok: true, grants: [] };
|
|
81
|
+
try {
|
|
82
|
+
const info = statSync(file);
|
|
83
|
+
if (process.platform !== 'win32') {
|
|
84
|
+
if ((info.mode & 0o022) !== 0)
|
|
85
|
+
return { ok: false, reason: `${file} is writable by its group or others; run chmod 600 on it` };
|
|
86
|
+
if (typeof process.getuid === 'function' && info.uid !== process.getuid())
|
|
87
|
+
return { ok: false, reason: `${file} is owned by another user` };
|
|
88
|
+
}
|
|
89
|
+
const data = JSON.parse(readFileSync(file, 'utf8'));
|
|
90
|
+
if (!Array.isArray(data.grants) || !data.grants.every(isGrant))
|
|
91
|
+
return { ok: false, reason: `${file} is malformed` };
|
|
92
|
+
return { ok: true, grants: data.grants };
|
|
93
|
+
}
|
|
94
|
+
catch {
|
|
95
|
+
return { ok: false, reason: `${file} cannot be read as delegation JSON` };
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
function writeGrants(grants, home) {
|
|
99
|
+
const file = delegationFile(home);
|
|
100
|
+
const unknown = grantsDirProblem(home);
|
|
101
|
+
if (unknown !== undefined)
|
|
102
|
+
return unknown;
|
|
103
|
+
mkdirSync(join(home, '.tslaws'), { recursive: true, mode: 0o700 });
|
|
104
|
+
const place = grantsDirProblem(home);
|
|
105
|
+
if (place !== undefined)
|
|
106
|
+
return place;
|
|
107
|
+
const temp = `${file}.${process.pid}.tmp`;
|
|
108
|
+
writeFileSync(temp, `${JSON.stringify({ grants }, null, 2)}\n`, { mode: 0o600 });
|
|
109
|
+
renameSync(temp, file);
|
|
110
|
+
return undefined;
|
|
111
|
+
}
|
|
112
|
+
/** The live grant for a project root. Real paths are compared, and a grant naming a symlink never matches. */
|
|
113
|
+
export function findGrant(root, now, home = userHome()) {
|
|
114
|
+
const real = realRoot(root);
|
|
115
|
+
if (real === undefined)
|
|
116
|
+
return { ok: false, reason: 'the project root does not exist' };
|
|
117
|
+
const inside = homeInsideRoot(home, real);
|
|
118
|
+
if (inside !== undefined)
|
|
119
|
+
return { ok: false, reason: inside };
|
|
120
|
+
const read = readGrants(home);
|
|
121
|
+
if (!read.ok)
|
|
122
|
+
return { ok: false, reason: read.reason };
|
|
123
|
+
const named = read.grants.filter((g) => same(g.root, real) && realRoot(g.root) !== undefined);
|
|
124
|
+
if (named.length === 0)
|
|
125
|
+
return { ok: false, reason: 'no delegation covers this project' };
|
|
126
|
+
const live = named
|
|
127
|
+
.filter((g) => Date.parse(g.expires) > now.getTime())
|
|
128
|
+
.sort((a, b) => Date.parse(b.expires) - Date.parse(a.expires))[0];
|
|
129
|
+
return live === undefined ? { ok: false, reason: 'the delegation has expired' } : { ok: true, grant: live };
|
|
130
|
+
}
|
|
131
|
+
/** Decides whether `accept` may run: a person at a terminal, else a live grant. CI never. */
|
|
132
|
+
export function acceptGate(input) {
|
|
133
|
+
const { env } = input;
|
|
134
|
+
if (env.CI !== undefined)
|
|
135
|
+
return { ok: false, message: 'accept records laws as correct and never runs under CI, even with a delegation' };
|
|
136
|
+
if (input.isTTY && env.TSLAWS_AGENT === undefined)
|
|
137
|
+
return { ok: true, delegated: false };
|
|
138
|
+
const verdict = findGrant(input.root, input.now ?? new Date(), input.home);
|
|
139
|
+
if (verdict.ok)
|
|
140
|
+
return { ok: true, delegated: true, grant: verdict.grant };
|
|
141
|
+
return {
|
|
142
|
+
ok: false,
|
|
143
|
+
message: `accept records laws as correct and needs a person at a terminal or a live delegation (${verdict.reason}); ${regrant}`,
|
|
144
|
+
};
|
|
145
|
+
}
|
|
146
|
+
/** The gate for acts only a person may do: a terminal, no agent marker, no CI. */
|
|
147
|
+
export function personOnly(input) {
|
|
148
|
+
return input.isTTY && input.env.TSLAWS_AGENT === undefined && input.env.CI === undefined;
|
|
149
|
+
}
|
|
150
|
+
/** Records a grant for a project; returns it, or the reason it was refused. */
|
|
151
|
+
export function grantFor(root, ms, now, home = userHome()) {
|
|
152
|
+
const real = realRoot(root);
|
|
153
|
+
if (real === undefined)
|
|
154
|
+
return `${root} does not exist`;
|
|
155
|
+
if (!same(resolve(root), real))
|
|
156
|
+
return `${root} is a symlink to ${real}; name the real directory`;
|
|
157
|
+
const inside = homeInsideRoot(home, real);
|
|
158
|
+
if (inside !== undefined)
|
|
159
|
+
return inside;
|
|
160
|
+
const read = readGrants(home);
|
|
161
|
+
if (!read.ok)
|
|
162
|
+
return read.reason;
|
|
163
|
+
const grant = { root: real, expires: new Date(now.getTime() + ms).toISOString() };
|
|
164
|
+
const problem = writeGrants([...read.grants.filter((g) => !same(g.root, real)), grant], home);
|
|
165
|
+
return problem ?? grant;
|
|
166
|
+
}
|
|
167
|
+
/** Removes the grants for a project; returns how many, or the reason it was refused. */
|
|
168
|
+
export function revokeFor(root, home = userHome()) {
|
|
169
|
+
const real = realRoot(root);
|
|
170
|
+
if (real === undefined)
|
|
171
|
+
return `${root} does not exist`;
|
|
172
|
+
const read = readGrants(home);
|
|
173
|
+
if (!read.ok)
|
|
174
|
+
return read.reason;
|
|
175
|
+
const kept = read.grants.filter((g) => !same(g.root, real));
|
|
176
|
+
if (kept.length !== read.grants.length) {
|
|
177
|
+
const problem = writeGrants(kept, home);
|
|
178
|
+
if (problem !== undefined)
|
|
179
|
+
return problem;
|
|
180
|
+
}
|
|
181
|
+
return read.grants.length - kept.length;
|
|
182
|
+
}
|
|
183
|
+
export function describeGrants(now, home = userHome()) {
|
|
184
|
+
const read = readGrants(home);
|
|
185
|
+
if (!read.ok)
|
|
186
|
+
return [`delegation unusable: ${read.reason}`];
|
|
187
|
+
if (read.grants.length === 0)
|
|
188
|
+
return ['no delegations'];
|
|
189
|
+
return read.grants.map((g) => `${Date.parse(g.expires) > now.getTime() ? 'live' : 'expired'} ${g.root} until ${g.expires}${g.note ? ` (${g.note})` : ''}`);
|
|
190
|
+
}
|
|
191
|
+
export function fileHash(path) {
|
|
192
|
+
return existsSync(path) ? createHash('sha256').update(readFileSync(path)).digest('hex') : 'none';
|
|
193
|
+
}
|
|
194
|
+
/** Appends the audit line for a delegated accept to `<project>/.tslaws/accept.log`. */
|
|
195
|
+
export function logDelegatedAccept(root, grant, before, after, now) {
|
|
196
|
+
const dir = join(root, '.tslaws');
|
|
197
|
+
mkdirSync(dir, { recursive: true });
|
|
198
|
+
appendFileSync(join(dir, 'accept.log'), `${now.toISOString()} delegated expires=${grant.expires} lock-before=${before} lock-after=${after}\n`);
|
|
199
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "tslaws",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "Runs and checks `law` declarations compiled by tsc-laws: property tests, SMT proofs, tamper lock.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"tslaws": "bin/tslaws.js"
|
|
@@ -71,11 +71,11 @@
|
|
|
71
71
|
}
|
|
72
72
|
},
|
|
73
73
|
"optionalDependencies": {
|
|
74
|
-
"tslaws-compiler-darwin-arm64": "0.
|
|
75
|
-
"tslaws-compiler-darwin-x64": "0.
|
|
76
|
-
"tslaws-compiler-linux-arm64-gnu": "0.
|
|
77
|
-
"tslaws-compiler-linux-x64-gnu": "0.
|
|
78
|
-
"tslaws-compiler-win32-x64-msvc": "0.
|
|
74
|
+
"tslaws-compiler-darwin-arm64": "0.5.0",
|
|
75
|
+
"tslaws-compiler-darwin-x64": "0.5.0",
|
|
76
|
+
"tslaws-compiler-linux-arm64-gnu": "0.5.0",
|
|
77
|
+
"tslaws-compiler-linux-x64-gnu": "0.5.0",
|
|
78
|
+
"tslaws-compiler-win32-x64-msvc": "0.5.0"
|
|
79
79
|
},
|
|
80
80
|
"publishConfig": {
|
|
81
81
|
"access": "public"
|