Skip to content
Merged
8 changes: 4 additions & 4 deletions docs/use-cases.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,8 @@ A catalog of use cases for structured-context, covering both direct CLI usage an
| Use case | Description | Status | Coverage |
|---|---|---|---|
| **Validate content** | Verify that space content conforms to schema, link integrity, rules, and hierarchy | | |
| — Validate a space | Check all files in a space in one pass | done | `sctx validate` · `/validate-space` command |
| — Validate a single file | Validate one file in context of its space | done | `sctx validate-file` · auto-validation hook on `.md` save |
Comment thread
mindsocket marked this conversation as resolved.
Resolved
| — Validate a space | Check all files in a space in one pass | done | `sctx validate` · `/validate-space` command · plugin hooks report issues introduced during a Claude turn |
| — Validate a single file | Validate one file in context of its space | done | `sctx validate-file` · `validateFile` API, e.g. for validation on save in an editor |
| — Watch for changes | Continuously re-validate as files are edited | done | `sctx validate --watch` |
| **Resolve validation errors** | Investigate and fix schema, link, or rule violations once identified | agent | structured-context skill (troubleshooting guide; `dump` for rule debugging) |

Expand Down Expand Up @@ -60,7 +60,7 @@ A catalog of use cases for structured-context, covering both direct CLI usage an

| Use case | Description | Status | Coverage |
|---|---|---|---|
| **Author new content compliantly** | Create or edit nodes in Obsidian while staying schema-conformant | partial | Validation hook on `.md` save; schema-driven templates; structured-context skill for inline guidance |
| **Author new content compliantly** | Create or edit nodes in Obsidian while staying schema-conformant | partial | Plugin hooks report issues introduced during a Claude turn; schema-driven templates; structured-context skill for inline guidance |
| **Discover and curate inputs** | Identify new information (research, signals, events) to add to a space and integrate it | none | — |

---
Expand Down Expand Up @@ -91,4 +91,4 @@ A catalog of use cases for structured-context, covering both direct CLI usage an
| Use case | Description | Status | Coverage |
|---|---|---|---|
| **Automate workflow rituals** | Run planning, review, or triage workflows against space content on a schedule or trigger | none | — |
| **Automate gardening and hygiene** | Scheduled or triggered cleanup: link repair, status updates, orphan triage | partial | `validate --watch` for live feedback; hooks for save-time checks; manual agent-driven triage |
| **Automate gardening and hygiene** | Scheduled or triggered cleanup: link repair, status updates, orphan triage | partial | `validate --watch` for live feedback; plugin hooks report issues introduced during a Claude turn; manual agent-driven triage |
37 changes: 20 additions & 17 deletions hook-test/harness.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,13 @@
* can inspect them after the run without relying on in-process buffering.
*/

import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { mkdirSync, writeFileSync } from 'node:fs';
import { join } from 'node:path';
import { query } from '@anthropic-ai/claude-agent-sdk';
import { runOnPrompt } from '../plugin/scripts/on-prompt';
import { runOnStop } from '../plugin/scripts/on-stop';
import { runPreEdit } from '../plugin/scripts/pre-edit';
import { loadState, type SessionState, stateFilePath } from '../plugin/scripts/state';

const SCTX_BIN = join(import.meta.dir, '..', 'src', 'index.ts');

Expand All @@ -33,11 +35,8 @@ export interface RunClaudeResult {
outputDir: string;
/** Directory where hook state files live during the session */
stateDir: string;
/**
* State entries captured by the PreToolUse hook before the Stop hook deletes the file.
* Each entry describes an Edit or Write operation on a .md file in a configured space.
*/
stateEntries: object[];
/** Session state as the Stop hook found it, before it cleared the baselines */
stateAtStop: SessionState;
/** All SDK messages written as JSONL */
messagesFile: string;
}
Expand All @@ -53,7 +52,7 @@ export async function runClaude(options: RunClaudeOptions): Promise<RunClaudeRes

const hookOpts = { stateDir, sctxBin: SCTX_BIN, configPath };
let stopResult: { hasNewErrors: boolean; errorMessage?: string } = { hasNewErrors: false };
let capturedStateEntries: object[] = [];
let stateAtStop: SessionState = { baseline: {}, latest: {} };
let actualSessionId = 'unknown';
const messages: object[] = [];

Expand All @@ -64,7 +63,19 @@ export async function runClaude(options: RunClaudeOptions): Promise<RunClaudeRes
cwd: fixtureDir,
additionalDirectories: [fixtureDir],
permissionMode: 'acceptEdits',
// Without this, the SDK loads ~/.claude settings and CLAUDE.md
settingSources: [],
hooks: {
UserPromptSubmit: [
{
hooks: [
async (input) => {
await runOnPrompt({ session_id: input.session_id, cwd: input.cwd }, hookOpts);
return {};
},
],
},
],
PreToolUse: [
{
matcher: 'Write|Edit',
Expand All @@ -87,15 +98,7 @@ export async function runClaude(options: RunClaudeOptions): Promise<RunClaudeRes
{
hooks: [
async (input) => {
// Capture state entries before runOnStop deletes the state file
const stateFile = join(stateDir, `sctx-hook-${input.session_id}.jsonl`);
if (existsSync(stateFile)) {
capturedStateEntries = readFileSync(stateFile, 'utf-8')
.trim()
.split('\n')
.filter(Boolean)
.map((l) => JSON.parse(l));
}
stateAtStop = loadState(stateFilePath(input.session_id, hookOpts));

stopResult = await runOnStop(
{
Expand Down Expand Up @@ -144,7 +147,7 @@ export async function runClaude(options: RunClaudeOptions): Promise<RunClaudeRes
sessionId: actualSessionId,
outputDir,
stateDir,
stateEntries: capturedStateEntries,
stateAtStop,
messagesFile,
};
}
30 changes: 12 additions & 18 deletions hook-test/hooks.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import { afterEach, describe, expect, it } from 'bun:test';
import { existsSync, readFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { loadState, stateFilePath } from '../plugin/scripts/state';
import { type IsolatedFixtures, isolateFixtures } from './fixture-utils';
import { runClaude } from './harness';

Expand All @@ -30,11 +31,10 @@ function makeOutputDir(): string {

describe('clean edit of valid file', () => {
it(
'captures an Edit state entry, exits 0, and cleans up the state file',
'baselines the space when the prompt is submitted and exits 0',
async () => {
fixtures = isolateFixtures();
const outputDir = makeOutputDir();
const validFile = join(fixtures.vaultDir, 'valid.md');

const result = await runClaude({
prompt: `Read valid.md, then change the title to "Modified Title". Only edit the file, no other output.`,
Expand All @@ -45,29 +45,25 @@ describe('clean edit of valid file', () => {

expect(result.exitCode).toBe(0);
expect(existsSync(join(outputDir, 'stop-hook-errors.txt'))).toBe(false);

const editEntry = result.stateEntries.find((e) => (e as { tool: string }).tool === 'Edit');
expect(editEntry).toBeDefined();
expect((editEntry as { file: string }).file).toBe(validFile);

// State entries captured before deletion — confirms the file was written
expect(result.stateEntries.length).toBeGreaterThan(0);
// Stop hook must delete the state file after analysis
expect(existsSync(join(result.stateDir, `sctx-hook-${result.sessionId}.jsonl`))).toBe(false);
expect(result.stateAtStop.baseline['test-space']?.path).toBe(fixtures.vaultDir);
// The Stop hook clears the baseline and keeps the results for the next prompt
const after = loadState(stateFilePath(result.sessionId, { stateDir: result.stateDir }));
expect(after.baseline).toEqual({});
expect(after.latest['test-space']).toBeDefined();
},
TEST_TIMEOUT,
);
});

describe('Write hook', () => {
describe('Write', () => {
it(
'captures a state entry with null errors when Claude writes a new .md file',
'exits 0 when Claude writes a valid new .md file',
async () => {
fixtures = isolateFixtures();
const outputDir = makeOutputDir();

const result = await runClaude({
prompt: `Create a new file called new-note.md in the current directory with this exact content:
prompt: `Create a new file at the relative path vault/new-note.md (inside the current working directory) with this exact content:
---
type: mission
parent: "[[Root]]"
Expand All @@ -83,10 +79,8 @@ A new note.`,
});

expect(result.exitCode).toBe(0);

const writeEntry = result.stateEntries.find((e) => (e as { tool: string }).tool === 'Write');
expect(writeEntry).toBeDefined();
expect((writeEntry as { errors: null }).errors).toBeNull();
expect(existsSync(join(fixtures.vaultDir, 'new-note.md'))).toBe(true);
expect(result.stateAtStop.baseline['test-space']?.issues['new-note.md']).toBeUndefined();
},
TEST_TIMEOUT,
);
Expand Down
111 changes: 111 additions & 0 deletions hook-test/unit/on-prompt.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,111 @@
/**
* Unit tests for plugin/scripts/on-prompt.ts
*
* Tests call runOnPrompt() directly — no Claude process involved.
*/

import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { runOnPrompt } from '../../plugin/scripts/on-prompt';
import { loadState, saveState, stateFilePath } from '../../plugin/scripts/state';
import { type IsolatedFixtures, isolateFixtures } from '../fixture-utils';

const SCTX_BIN = join(import.meta.dir, '../../src/index.ts');

let fixtures: IsolatedFixtures;
let stateDir: string;
let sessionId: string;

beforeEach(() => {
fixtures = isolateFixtures();
stateDir = join(tmpdir(), `ost-on-prompt-state-${crypto.randomUUID()}`);
sessionId = crypto.randomUUID();
});

afterEach(() => {
fixtures.cleanup();
rmSync(stateDir, { recursive: true, force: true });
});

const opts = () => ({ stateDir, sctxBin: SCTX_BIN, configPath: fixtures.configPath });
const stateFile = () => stateFilePath(sessionId, opts());

describe('Baselines', () => {
it('baselines a space inside the session directory', async () => {
await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

const { baseline, latest } = loadState(stateFile());
expect(Object.keys(baseline)).toEqual(['test-space']);
expect(baseline['test-space']!.path).toBe(fixtures.vaultDir);
expect(Object.keys(baseline['test-space']!.issues)).toEqual(['broken.md']);
expect(baseline['test-space']!.issues['broken.md']).toContain('broken-link:[[Nonexistent Node]]');
expect(latest).toEqual(baseline);
});

it('baselines a space that contains the session directory', async () => {
const subdir = join(fixtures.vaultDir, 'sub');
mkdirSync(subdir);

await runOnPrompt({ session_id: sessionId, cwd: subdir }, opts());

expect(Object.keys(loadState(stateFile()).baseline)).toEqual(['test-space']);
});

it('writes no state when no space is related to the session directory', async () => {
// A sibling of the fixture dir, not tmpdir() itself: on Linux the fixture lives under tmpdir()
const unrelated = join(tmpdir(), `ost-on-prompt-unrelated-${crypto.randomUUID()}`);

await runOnPrompt({ session_id: sessionId, cwd: unrelated }, opts());

expect(existsSync(stateFile())).toBe(false);
});

it('does nothing without a cwd', async () => {
await runOnPrompt({ session_id: sessionId }, opts());

expect(existsSync(stateFile())).toBe(false);
});
});

describe('Existing state', () => {
it('keeps an existing baseline when the previous Stop never ran', async () => {
await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());
writeFileSync(
join(fixtures.vaultDir, 'valid.md'),
'---\ntype: mission\nparent: "[[Ghost Node]]"\nstatus: identified\n---\n\n# Test Title\n',
);

await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(loadState(stateFile()).baseline['test-space']!.issues['valid.md']).toBeUndefined();
});

it('reuses the latest results without validating when the space is unchanged', async () => {
await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());
// Simulate a completed turn, and mark the latest results so reuse is observable
const state = loadState(stateFile());
const latest = state.latest['test-space']!;
latest.issues = { 'marker.md': [] };
saveState(stateFile(), { baseline: {}, latest: { 'test-space': latest } });

await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(Object.keys(loadState(stateFile()).baseline['test-space']!.issues)).toEqual(['marker.md']);
});

it('validates again when the space has changed since the latest results', async () => {
await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());
const state = loadState(stateFile());
saveState(stateFile(), { baseline: {}, latest: state.latest });
writeFileSync(
join(fixtures.vaultDir, 'broken.md'),
'---\ntype: mission\nparent: "[[Root]]"\nstatus: identified\n---\n\n# Broken Note\n',
);

await runOnPrompt({ session_id: sessionId, cwd: fixtures.fixtureDir }, opts());

expect(loadState(stateFile()).baseline['test-space']!.issues).toEqual({});
});
});
Loading
Loading