@litfamily/litgrok 1.0.28 → 1.0.30

package/bin/litgrok.mjs

@@ -6,6 +6,7 @@ import { homedir } from 'node:os';
 import { basename, dirname, join, relative, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { renderMark, terminalMode } from '../.grok/hooks/lit-mark.mjs';
+import { applyStoredGround, backupIfSectionAbsent, decideGround, groundReport, ruleSourceForInstall, runGround } from './ground-rule.mjs';
 import { installNotifications, installStatusLine, removeNotifications, removeStatusLine } from './status-line-config.mjs';
 
 const PACKAGE_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -208,7 +209,7 @@ const PRE_MANIFEST_LEGACY_PAYLOAD_HASHES = Object.freeze({
   'skills/text-naturalization/SKILL.md': 'aa1ff8f68ab0bf71cb47818b536c4a2934da65adb413ee43ec5839b540b2df8e',
   'skills/lit-korean/SKILL.md': 'dc2e4b0ea2ff6acca904f05767a62448387571e4183a615d5e53b230704ee828',
 });
-const USAGE = 'Usage: litgrok [install|uninstall] [--user|--project] [--status-line] [--notify] [--dry-run] [--no-color] [--yes]\n       litgrok auto-handoff on [percent]|off|status\n       litgrok doctor [--no-color]\n       litgrok motion-runtime install|status\nTypographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit ca251e3.\n';
+const USAGE = 'Usage: litgrok [install|uninstall] [--user|--project] [--status-line] [--notify] [--dry-run] [--no-color] [--yes] [--no-ground]\n       litgrok ground on|off|status\n       litgrok ground project [--dir <path>] [--remove] [--dry-run]\n       litgrok auto-handoff on [percent]|off|status\n       litgrok doctor [--no-color]\n       litgrok motion-runtime install|status\nTypographic-motion engine adapted from mexicat/pdoom-video (MIT, Giacomo Magnanini), commit ca251e3.\n';
 const BRAILLE_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 const SPINNER_INTERVAL_MS = 80;
 const CLEAR_LINE = '\r\u001b[2K';
@@ -217,7 +218,7 @@ function parseInstall(args) {
   const remaining = [...args];
   let command = 'install';
   if (['install', 'uninstall'].includes(remaining[0])) command = remaining.shift();
-  if (remaining.some((argument) => !['--user', '--project', '--status-line', '--notify', '--dry-run', '--no-color', '--yes'].includes(argument))) return null;
+  if (remaining.some((argument) => !['--user', '--project', '--status-line', '--notify', '--dry-run', '--no-color', '--yes', '--no-ground'].includes(argument))) return null;
   if (remaining.includes('--user') && remaining.includes('--project')) return null;
   // Both opt-ins change ~/.grok/config.toml, which only a user install may touch.
   if ((remaining.includes('--status-line') || remaining.includes('--notify')) && (command !== 'install' || !remaining.includes('--user'))) return null;
@@ -226,6 +227,7 @@ function parseInstall(args) {
     dryRun: remaining.includes('--dry-run'),
     noColor: remaining.includes('--no-color'),
     yes: remaining.includes('--yes'),
+    noGround: remaining.includes('--no-ground'),
     statusLine: remaining.includes('--status-line'),
     notify: remaining.includes('--notify'),
     scope: remaining.includes('--user') ? 'user' : 'project',
@@ -833,7 +835,7 @@ async function runDoctor(args, { env, stdout, stderr, fetchFn }) {
     return 1;
   }
   const current = packageVersion();
-  stdout.write(`litgrok ${current}\n`);
+  stdout.write(`litgrok ${current}\n${groundReport(env)}\n`);
   if (UPDATE_OPT_OUTS.some((name) => Object.hasOwn(env, name))) return 0;
   let latest;
   try {
@@ -855,6 +857,7 @@ export async function run(args, context = {}) {
     const { runAutoHandoff } = await import('../.grok/hooks/auto-handoff.mjs');
     return runAutoHandoff(args.slice(1), { env: context.env ?? process.env, stdout: context.stdout ?? process.stdout, stderr: context.stderr ?? process.stderr, cwd: context.cwd ?? process.cwd() });
   }
+  if (args[0] === 'ground') return runGround(args.slice(1), context);
   if (args[0] === 'doctor') {
     return runDoctor(args.slice(1), {
       env: context.env ?? process.env,
@@ -906,7 +909,7 @@ export async function run(args, context = {}) {
     if (projectHooksIncluded(files)) stdout.write('Project hooks require a trusted Git project root: use /hooks-trust or, on Grok Build 1.0.13, grok --trust inspect --json; the installer never runs git init or changes trust.\n');
   }
 
-  const files = discoveredPayload ? filesFromPayload(discoveredPayload) : null;
+  let files = discoveredPayload ? filesFromPayload(discoveredPayload) : null;
   const payloadElapsed = payloadError ? null : elapsedSince(payloadStarted);
   const colors = printInstallFrame(stdout, options, env, files?.length, displayRoot);
 
@@ -930,6 +933,33 @@ export async function run(args, context = {}) {
     return 0;
   }
 
+  let includeGround = true;
+  let groundAfter = null;
+  let cleanupGround = () => {};
+  if (options.command === 'install') {
+    try {
+      const decision = await decideGround({
+        scope: options.scope,
+        yes: options.yes,
+        noGround: options.noGround,
+        env,
+        stdin,
+        stdout,
+        home,
+      });
+      includeGround = decision.include;
+      groundAfter = decision.afterWrite;
+      if (!decision.include) {
+        const prepared = ruleSourceForInstall(files);
+        files = prepared.files;
+        cleanupGround = prepared.cleanup;
+      }
+    } catch (error) {
+      stderr.write(`litgrok: ${error instanceof Error ? error.message : String(error)}\n`);
+      return 1;
+    }
+  }
+
   const progress = new InstallProgress(stdout, colors);
   progress.open();
   let step = 'PAYLOAD';
@@ -1046,6 +1076,7 @@ export async function run(args, context = {}) {
         throw error;
       }
       const statusDetail = configDetail(statusLineResult, notifyResult);
+      if (groundAfter) applyStoredGround(home, groundAfter);
       skipStep(progress, 'WRITE', `SKIPPED · 0 written · ${states.counts.current} already-current${statusDetail}`);
       const receipt = receiptCard(options, displayRoot, colors, { status: 'Already current', written: 0, current: states.counts.current });
       progress.close();
@@ -1059,8 +1090,11 @@ export async function run(args, context = {}) {
     try {
       for (let index = 0; index < files.length; index += 1) {
         if (states.states[index] === 'current') continue;
-        const { source, target } = files[index];
+        const { source, target, relativePath } = files[index];
         mkdirSync(dirname(target), { recursive: true });
+        if (includeGround && normalizedRelativePath(relativePath) === 'rules/00-litgrok.md' && states.states[index] !== 'missing') {
+          backupIfSectionAbsent(target);
+        }
         if (states.states[index] === 'owned') replaceOwnedFile(source, target);
         else copyFileSync(source, target, constants.COPYFILE_EXCL);
         installed += 1;
@@ -1072,6 +1106,7 @@ export async function run(args, context = {}) {
       const notifyResult = options.notify ? installNotifications(root) : null;
       const legacyDetail = removedLegacy === 0 ? '' : ` · ${removedLegacy} legacy removed`;
       const statusDetail = configDetail(statusLineResult, notifyResult);
+      if (groundAfter) applyStoredGround(home, groundAfter);
       progress.finish('ok', 'WRITE', `${installed} written · ${states.counts.current} already-current · ${states.counts.owned} owned${legacyDetail}${statusDetail}`, elapsedSince(writeStarted));
     } catch (error) {
       progress.finish('failed', 'WRITE', errorText(error), elapsedSince(writeStarted));
@@ -1086,6 +1121,8 @@ export async function run(args, context = {}) {
     progress.close();
     reportFailure(error, { stderr, stdout, options, root: displayRoot, colors, step });
     return 1;
+  } finally {
+    cleanupGround();
   }
 }
 

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="local: 1.0.28"><title>local: 1.0.28</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="290" transform="scale(.1)">local</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.28</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="local: 1.0.30"><title>local: 1.0.30</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="290" transform="scale(.1)">local</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.30</text></g></svg>

package/docs/reference.md

@@ -80,7 +80,7 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 Pin a version when you need a reproducible install:
 
 ```bash
-npm exec --yes --package @litfamily/litgrok@1.0.28 -- litgrok install
+npm exec --yes --package @litfamily/litgrok@1.0.30 -- litgrok install
 ```
 
 Preview without writing files:
@@ -103,7 +103,7 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok install --user
 npm exec --yes --package @litfamily/litgrok@latest -- litgrok doctor
 ```
 
-`doctor` is read-only. It prints the package version, asks the npm registry for the latest stable `@litfamily/litgrok` with a 3-second limit, and adds `newer version available: <version> (run: npm exec --yes --package @litfamily/litgrok@latest -- litgrok install)` when one exists. It prints nothing more when you are current, and one `update check unavailable` line when the registry cannot be reached. It never installs or writes files. `NO_UPDATE_NOTIFIER`, `CI` or `LITGROK_NO_UPDATE_CHECK` (present, even empty) skips the registry request.
+`doctor` is read-only. It prints the package version and one `GROUND:` line for the section at the end of `~/.grok/rules/00-litgrok.md`: `present v=<version>`, `stale v=<version>`, `absent`, `malformed` or `off`. It asks the npm registry for the latest stable `@litfamily/litgrok` with a 3-second limit, and adds `newer version available: <version> (run: npm exec --yes --package @litfamily/litgrok@latest -- litgrok install)` when one exists. It adds nothing further when you are current, and one `update check unavailable` line when the registry cannot be reached. It never installs or writes files. `NO_UPDATE_NOTIFIER`, `CI` or `LITGROK_NO_UPDATE_CHECK` (present, even empty) skips the registry request. `litgrok ground off` removes that section and keeps it off; `litgrok ground on` restores it; `install --no-ground` skips it for that run. `litgrok ground project` writes the repo copy at `.grok/rules/10-litgrok-ground.md` and refuses a symlink, a non-directory path, or a file it does not own.
 
 ### Persistent status line (opt-in)
 

package/docs/reference_ko-KR.md

@@ -81,7 +81,7 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok install
 재현 가능한 설치는 버전을 고정합니다.
 
 ```bash
-npm exec --yes --package @litfamily/litgrok@1.0.28 -- litgrok install
+npm exec --yes --package @litfamily/litgrok@1.0.30 -- litgrok install
 ```
 
 파일을 쓰지 않고 미리보기:
@@ -104,7 +104,7 @@ npm exec --yes --package @litfamily/litgrok@latest -- litgrok install --user
 npm exec --yes --package @litfamily/litgrok@latest -- litgrok doctor
 ```
 
-`doctor`는 읽기만 합니다. 패키지 버전을 출력하고, npm 레지스트리에 최신 안정 `@litfamily/litgrok` 버전을 최대 3초 동안 물어봅니다. 더 새 버전이 있으면 `newer version available: <version> (run: npm exec --yes --package @litfamily/litgrok@latest -- litgrok install)` 한 줄을 더합니다. 최신이면 아무것도 더하지 않고, 레지스트리에 닿지 못하면 `update check unavailable` 한 줄만 출력합니다. 설치하거나 파일을 쓰지 않습니다. `NO_UPDATE_NOTIFIER`, `CI`, `LITGROK_NO_UPDATE_CHECK` 중 하나가 있으면(값이 비어 있어도) 레지스트리에 묻지 않습니다.
+`doctor`는 읽기만 합니다. 패키지 버전을 출력하고, `~/.grok/rules/00-litgrok.md` 끝 구간에 대해 `GROUND:` 한 줄을 냅니다. 값은 `present v=<version>`, `stale v=<version>`, `absent`, `malformed`, `off` 중 하나입니다. npm 레지스트리에 최신 안정 `@litfamily/litgrok` 버전을 최대 3초 동안 물어봅니다. 더 새 버전이 있으면 `newer version available: <version> (run: npm exec --yes --package @litfamily/litgrok@latest -- litgrok install)` 한 줄을 더합니다. 최신이면 그 이상은 더하지 않고, 레지스트리에 닿지 못하면 `update check unavailable` 한 줄을 출력합니다. 설치하거나 파일을 쓰지 않습니다. `NO_UPDATE_NOTIFIER`, `CI`, `LITGROK_NO_UPDATE_CHECK` 중 하나가 있으면(값이 비어 있어도) 레지스트리에 묻지 않습니다. `litgrok ground off`는 그 구간을 빼고 꺼 둔 채로 두며, `litgrok ground on`은 다시 넣습니다. `install --no-ground`는 그 한 번만 건너뜁니다. `litgrok ground project`는 저장소 복사본을 `.grok/rules/10-litgrok-ground.md`에 쓰며, 심볼릭 링크, 디렉터리가 아닌 경로, 자신이 소유하지 않은 파일은 거절합니다.
 
 ### 지속 상태 행 (선택)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litgrok",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "Installer for LitGrok: skills, a project rule and hooks that help xAI Grok Build sessions plan, build, check and hand off their work.",
   "keywords": [
     "grok",

package/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "litgrok",
-  "version": "1.0.28",
+  "version": "1.0.30",
   "description": "Grok Build skills, project rules, and bounded lifecycle hooks for evidence-first lit work.",
   "author": {
     "name": "LitGrok contributors"