{"_id":"@amit-t/stet","name":"@amit-t/stet","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@amit-t/stet","version":"0.1.0","description":"Local Markdown review utility for engineers and AI agents: threaded comments that live inside Markdown files with byte-splice persistence.","keywords":["markdown","review","comments","annotations","local-first","cli","agents"],"license":"MIT","type":"module","engines":{"node":">=20.10"},"bin":{"stet":"dist/cli/main.js","s":"dist/cli/main.js","redline":"dist/cli/main.js","rl":"dist/cli/main.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./core":{"types":"./dist/core/index.d.ts","import":"./dist/core/index.js"},"./safety":{"types":"./dist/safety/index.d.ts","import":"./dist/safety/index.js"},"./server":{"types":"./dist/server/index.d.ts","import":"./dist/server/index.js"}},"dependencies":{"js-yaml":"^4.2.0","remark-parse":"^11.0.0","unified":"^11.0.5"},"devDependencies":{"@types/js-yaml":"^4.0.9","@types/mdast":"^4.0.4","@types/node":"^22.10.0","happy-dom":"latest","typescript":"^5.7.0","vitest":"^4.1.8"},"repository":{"type":"git","url":"git+https://github.com/amit-t/stet.git"},"homepage":"https://github.com/amit-t/stet#readme","bugs":{"url":"https://github.com/amit-t/stet/issues"},"publishConfig":{"access":"public","registry":"https://registry.npmjs.org/"},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","test":"vitest run tests/core tests/cli tests/safety tests/server tests/security tests/browser","test:core":"vitest run tests/core","test:cli":"vitest run tests/cli","test:server":"vitest run tests/server tests/security","test:browser":"vitest run tests/browser","test:packaging":"pnpm run build && vitest run tests/packaging","ci":"pnpm run typecheck && pnpm test && pnpm run test:packaging","pack:dry":"pnpm pack --dry-run"},"_id":"@amit-t/stet@0.1.0","_integrity":"sha512-buRrT3pKyQExWA6SItUAEbKrc5AEvYR7Jjq/DBpMRzxjJ1kzAYMPAnl+UwRRXccgutKb23Qen6J0VgnNEBkKlw==","_resolved":"/private/var/folders/sl/xqtndrqs2nndnx2l8g6ld8vm0000gn/T/c16175b6503fd22295044218c94918bd/amit-t-stet-0.1.0.tgz","_from":"file:amit-t-stet-0.1.0.tgz","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-buRrT3pKyQExWA6SItUAEbKrc5AEvYR7Jjq/DBpMRzxjJ1kzAYMPAnl+UwRRXccgutKb23Qen6J0VgnNEBkKlw==","shasum":"05419a96388d4f5e7d3ef014cfbcc46896bcdbbd","tarball":"https://registry.npmjs.org/@amit-t/stet/-/stet-0.1.0.tgz","fileCount":167,"unpackedSize":378993,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDQsrrYB3JVJPLUhlMjdyC34N4aPt78kOZNrDinwqiJNQIhALkdyNfLGQKA4mhL4ybCgbeeoeBtyaNzmldH8GEBb247"}]},"_npmUser":{"name":"amit-t","email":"tiwari.m.amit@gmail.com"},"directories":{},"maintainers":[{"name":"amit-t","email":"tiwari.m.amit@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/stet_0.1.0_1780848147413_0.16077938286130777"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-07T16:02:27.243Z","0.1.0":"2026-06-07T16:02:27.576Z","modified":"2026-06-07T16:02:27.774Z"},"maintainers":[{"name":"amit-t","email":"tiwari.m.amit@gmail.com"}],"description":"Local Markdown review utility for engineers and AI agents: threaded comments that live inside Markdown files with byte-splice persistence.","homepage":"https://github.com/amit-t/stet#readme","keywords":["markdown","review","comments","annotations","local-first","cli","agents"],"repository":{"type":"git","url":"git+https://github.com/amit-t/stet.git"},"bugs":{"url":"https://github.com/amit-t/stet/issues"},"license":"MIT","readme":"# Stet\n\nStet is a local-first Markdown review utility. It opens one Markdown file in a loopback browser UI, lets humans add threaded review comments, saves those threads back into the same Markdown file, and lets AI agents reply through a safe CLI.\n\n- npm package: `@amit-t/stet`\n- binaries: `stet`, `s`; legacy aliases: `redline`, `rl`\n- marker: `stet:thread`\n- thread IDs: `stt_...`\n- transient state: `.stet/`\n\n## Install\n\n### Install from Amit's local checkout\n\nUse this when the repo already exists at `/Users/amittiwari/Projects/Tools-Utilities/stet`:\n\n```zsh\ncd /Users/amittiwari/Projects/Tools-Utilities/stet\npnpm install\npnpm run build\npnpm link --global\nrehash\nstet --version\ns --help\n```\n\nIf `pnpm link --global` says the global bin directory is not configured, run `pnpm setup`, restart the shell, then repeat `pnpm link --global`.\n\n### No-clone one-shot usage after publish\n\nAfter `stet` is published to npm, anyone can run Stet without cloning this repo:\n\n```zsh\nnpx @amit-t/stet@latest README.md\n# or\npnpm dlx @amit-t/stet README.md\n```\n\n`npx`/`pnpm dlx` downloads the package to a temporary tool cache, runs the `stet` binary, and leaves no project dependency behind. Pass the same flags you would pass to `stet`:\n\n```zsh\nnpx @amit-t/stet@latest --author \"Amit\" --app \"Google Chrome\" docs/prd/00-stet-master-prd.md\npnpm dlx @amit-t/stet --no-open --port 43117 docs/prd/00-stet-master-prd.md\n```\n\n### Persistent install after publish\n\nFor a permanent terminal command without cloning the repo:\n\n```zsh\npnpm add --global @amit-t/stet\n# or, if you prefer npm for global tools:\nnpm install -g @amit-t/stet\n\nstet --version\nstet README.md\n```\n\n## Quick start\n\n```zsh\nstet README.md\n# or\ns README.md\n```\n\nUseful launch flags:\n\n```zsh\nstet --author \"Amit\" README.md\nstet --app \"Google Chrome\" README.md\nstet --port 43117 README.md\nstet --no-open README.md\n```\n\nThe server binds to `127.0.0.1`, sets an HttpOnly `SameSite=Strict` cookie, and opens `http://127.0.0.1:<port>/`. The token is never placed in the URL.\n\n## Browser review UI\n\nThe UI includes:\n\n- top bar with file name, dirty/saved state, open-thread count, Save, Reload, and patch preview;\n- rendered Markdown body with commentable headings and paragraphs;\n- `+` affordances, double-click comments, keyboard `c` on focused blocks, and document-level comments;\n- side-panel thread cards with replies, resolve/reopen controls, orphan and content-drift warnings;\n- localStorage draft recovery keyed by file path and loaded file hash;\n- conflict banner when the file changes on disk before save.\n\nResolved threads are collapsed by default. Orphaned threads appear under **Needs re-attach** and remain preserved in the Markdown file.\n\n## Agent CLI\n\nAgents should use CLI commands instead of hand-editing markers:\n\n```zsh\nstet list --json FILE.md\nstet reply FILE.md --thread stt_... --author Claude --message \"I updated the paragraph above.\"\nstet resolve FILE.md --thread stt_... --author Claude --message \"Resolved by the edit above.\"\nstet --print-agent-protocol\n```\n\nA helper exists for smoke tests and scripts:\n\n```zsh\nstet comment FILE.md --target paragraph:0 --author Amit --message \"Please tighten this.\"\n```\n\nFull protocol: [`docs/AGENT_PROTOCOL.md`](docs/AGENT_PROTOCOL.md).\n\n## Storage format\n\nThreads are stored inline as structured HTML-comment markers plus a generated visible blockquote:\n\n```markdown\n<!-- stet:thread\nversion: 1\nid: stt_20260607_150015_7f3a9c\nstatus: open\ncreated_at: 2026-06-07T15:00:15Z\nupdated_at: 2026-06-07T15:00:15Z\ntarget:\n  kind: paragraph\n  heading_path:\n    - Product goals\n  block_ordinal: 0\n  source_hash: sha256:...\n  quote: Product goals\nmessages:\n  - author: Amit\n    created_at: 2026-06-07T15:00:15Z\n    body: |-\n      This needs a clearer agent workflow.\n-->\n> [!NOTE]\n> **Review thread `stt_20260607_150015_7f3a9c` — open**\n>\n> **Amit** · 2026-06-07 15:00 UTC\n>\n> This needs a clearer agent workflow.\n<!-- /stet:thread -->\n```\n\nThe structured marker is the source of truth. The blockquote is regenerated from marker data on save. Message bodies containing unsafe `--` sequences are escaped in the structured marker so they cannot terminate the HTML comment early, then decoded losslessly when Stet parses the thread.\n\n## Write safety and formatter caveats\n\nStet saves by byte splices only. It does not stringify or reformat the whole Markdown document. Tests cover preservation of LF, CRLF, BOM, final-newline state, trailing spaces, list markers, reference links, and paragraph wrapping outside expected splice ranges.\n\nFormatter caveat: if an external formatter rewrites the file while Stet is open, Stet detects the file hash change and blocks save. Reload before saving staged comments. MVP intentionally has no force-save.\n\nBackups are written before replacement:\n\n```text\n.stet/\n  .gitignore      # contains *\n  backups/\n  locks/\n```\n\n## Security model\n\nStet is local-only and has no telemetry.\n\n- Binds to `127.0.0.1` by default.\n- Serves only the selected Markdown file and bundled UI assets.\n- Uses an HttpOnly `SameSite=Strict` cookie token; missing/wrong tokens are rejected for API routes.\n- Validates `Host` to reject DNS rebinding attempts.\n- Sends `Referrer-Policy: no-referrer`.\n- Sends restrictive CSP: self-only scripts/styles, self/data images, no objects/forms/framing.\n- Escapes raw Markdown HTML by default.\n- Blocks remote Markdown images/resources by default.\n\n## Development\n\nStet uses pnpm for repository development. Keep `pnpm-lock.yaml` as the only package-manager lockfile.\n\n```zsh\npnpm install\npnpm run typecheck\npnpm test\npnpm run test:packaging\npnpm run ci\npnpm run pack:dry\n```\n\nTest groups:\n\n- `tests/core/` parser, anchors, thread serialization, byte-splice writer.\n- `tests/server/` local server save/reopen/conflict flow.\n- `tests/security/` token, Host, CSP, no-referrer, remote-resource blocking.\n- `tests/browser/` browser UI smoke using a DOM-compatible runtime.\n- `tests/packaging/` package metadata and built CLI smoke.\n\n## Release gates\n\nMVP release requires:\n\n1. core parser/splice tests pass;\n2. server, security, and browser smoke tests pass;\n3. `stet --version`, `--help`, `--print-agent-protocol` work;\n4. README documents install, usage, storage, security, formatter caveats, and agent protocol;\n5. release notes list MVP limitations;\n6. dogfood run against the master PRD or a byte-identical copy.\n\n## MVP limitations\n\nSee [`docs/RELEASE_NOTES.md`](docs/RELEASE_NOTES.md). Current MVP does not support list-item, table-row, or text-range comments.\n","readmeFilename":"README.md","_rev":"1-57d4ed855c7445fd07a89005d3edbd9f"}