@m2015agg/git-skill 0.5.8 → 0.5.9
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/dist/commands/init.js
CHANGED
|
@@ -6,7 +6,7 @@ import { installHook } from "../util/hooks.js";
|
|
|
6
6
|
import { isGitRepo } from "../util/git.js";
|
|
7
7
|
import { upsertSection } from "../util/claude-md.js";
|
|
8
8
|
import { getSkillDoc } from "./docs.js";
|
|
9
|
-
import { WALKTHROUGH, REVIEW_COMMAND, PLAN_COMMAND, IMPLEMENT_COMMAND, FINALIZE_COMMAND } from "../templates/walkthrough.js";
|
|
9
|
+
import { WALKTHROUGH, REVIEW_COMMAND, PLAN_COMMAND, IMPLEMENT_COMMAND, FINALIZE_COMMAND, TRACE_COMMAND, HISTORICAL_CONTEXT_SKILL } from "../templates/walkthrough.js";
|
|
10
10
|
import { runContextUpdate } from "./context-update.js";
|
|
11
11
|
function write(msg) { process.stdout.write(msg); }
|
|
12
12
|
export function initCommand() {
|
|
@@ -98,6 +98,27 @@ export function initCommand() {
|
|
|
98
98
|
else {
|
|
99
99
|
write(" /finalize — already exists (not overwritten)\n");
|
|
100
100
|
}
|
|
101
|
+
// Install trace command
|
|
102
|
+
const tracePath = join(walkthroughDir, "trace.md");
|
|
103
|
+
if (!existsSync(tracePath)) {
|
|
104
|
+
writeFileSync(tracePath, TRACE_COMMAND);
|
|
105
|
+
write(" /trace — debug via git history (Missing Guard, Parallel Evolution, Stale Side Effect) (NEW)\n");
|
|
106
|
+
}
|
|
107
|
+
else {
|
|
108
|
+
write(" /trace — already exists (not overwritten)\n");
|
|
109
|
+
}
|
|
110
|
+
// Install historical-context-debugging skill
|
|
111
|
+
write(" Installing skills...\n");
|
|
112
|
+
const skillDir = join(cwd, ".claude", "skills", "historical-context-debugging");
|
|
113
|
+
const skillPath = join(skillDir, "SKILL.md");
|
|
114
|
+
if (!existsSync(skillPath)) {
|
|
115
|
+
mkdirSync(skillDir, { recursive: true });
|
|
116
|
+
writeFileSync(skillPath, HISTORICAL_CONTEXT_SKILL);
|
|
117
|
+
write(" historical-context-debugging — auto-triggered when code looks correct but behaves wrong (NEW)\n");
|
|
118
|
+
}
|
|
119
|
+
else {
|
|
120
|
+
write(" historical-context-debugging — already exists (not overwritten)\n");
|
|
121
|
+
}
|
|
101
122
|
// 6. Run snapshot
|
|
102
123
|
if (!opts.skipSnapshot) {
|
|
103
124
|
write("5. Running initial snapshot...\n");
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACxF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;
|
|
1
|
+
{"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/commands/init.ts"],"names":[],"mappings":"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"}
|
|
@@ -3,3 +3,5 @@ export declare const PLAN_COMMAND = "---\ndescription: \"Plan a feature with git
|
|
|
3
3
|
export declare const IMPLEMENT_COMMAND = "---\ndescription: \"Implement a planned feature with TDD and frequent commits\"\n---\n\n# Implementation Phase\n\nImplement feature according to the plan file.\n\n**PROCESS:**\n\n1. **Read Plan**: Read the plan file carefully\n2. **Create Branch**:\n ```bash\n git checkout -b [feature-name]\n git push -u origin [feature-name]\n ```\n3. **Create Draft PR**:\n ```bash\n gh pr create --draft --title \"WIP: [Feature Name]\" --body \"See docs/plans/...\"\n ```\n4. **Follow TDD** (Red \u2192 Green \u2192 Refactor):\n - Write test that fails\n - Implement minimal code to pass\n - Refactor while keeping tests green\n\n5. **For Each Task**:\n - Make changes following existing patterns in the codebase\n - Run tests after each change\n - Before committing, verify against history:\n ```bash\n git add .\n git-skill verify\n ```\n If BLOCK: stop and discuss. If WARN: note it and proceed carefully.\n - Push commits frequently (backup points):\n ```bash\n git commit -m \"wip: [task]\" && git push\n ```\n\n6. **STOP**: Notify completion \u2014 DO NOT finalize or merge\n\n**IMPORTANT:**\n- Follow plan exactly \u2014 don't deviate without asking\n- Push commits often (rollback points)\n- Keep user updated every 3-4 tasks\n- DO NOT finalize \u2014 just implement\n";
|
|
4
4
|
export declare const FINALIZE_COMMAND = "---\ndescription: \"Finalize a feature \u2014 tests, lint, commit, PR ready\"\n---\n\n# Finalization Phase\n\nFinalize the implemented feature.\n\n**PROCESS:**\n\n1. **Verify Tests Pass**:\n ```bash\n # Run your project's test suite\n npm test # Node.js\n # pytest tests/ # Python\n # cargo test # Rust\n ```\n If tests fail, STOP and return to implementation.\n\n2. **Run git-skill verify**:\n ```bash\n git-skill verify\n ```\n Address any WARN or BLOCK findings before proceeding.\n\n3. **Update Documentation**: Add/update docs if needed\n\n4. **Create Final Commit**:\n ```bash\n git add .\n git commit -m \"feat: [description]\n\n Closes #[issue-number]\"\n git push\n ```\n\n5. **Convert PR to Ready**:\n ```bash\n gh pr ready\n ```\n\n6. **Run Final Verification**:\n ```bash\n git-skill doctor\n git-skill hotspots --limit 3\n ```\n Show output \u2014 never claim completion without proof.\n\n7. **STOP**: Report completion with PR link and verification output\n\n**CHECKLIST:**\n- [ ] All tests passing\n- [ ] `git-skill verify` \u2014 no BLOCK findings\n- [ ] Documentation updated\n- [ ] Commit message follows conventions\n- [ ] PR converted to ready\n- [ ] Verification output shown\n\n**IMPORTANT:**\n- NEVER skip verification\n- NEVER merge PR \u2014 user reviews and merges\n- If anything fails, return to implementation\n";
|
|
5
5
|
export declare const REVIEW_COMMAND = "---\ndescription: \"Code review with git history verification \u2014 checks for repeated mistakes before merge\"\n---\n\n# Code Review with History Verification\n\nReview the current branch changes before merging.\n\n**PROCESS:**\n\n1. **Run tests**:\n ```bash\n # Run the project's test suite (adjust command for your project)\n npm test # Node.js\n # pytest # Python\n # cargo test # Rust\n ```\n\n2. **Git History Verification** (prevent re-trying failed approaches):\n ```bash\n git-skill verify\n ```\n If `git-skill verify` returns WARN or BLOCK:\n - **BLOCK**: STOP. This change re-introduces something that was explicitly reverted. Ask the user before proceeding.\n - **WARN**: Note the warning. Check if the current approach addresses the previous failure. Proceed with caution.\n - **PASS**: No concerns from history.\n\n3. **Review scope and codebase health**:\n ```bash\n git-skill diff-summary HEAD~5..HEAD # summarize what changed in this branch\n git-skill hotspots --limit 5 # flag churning files\n ```\n Flag any files being modified that appear in the hotspots list.\n\n4. **Review against criteria**:\n - **Critical** (must fix): Security vulnerabilities, data loss risks, breaking changes, tests failing\n - **Major** (should fix): Missing error handling, pattern violations, missing tests\n - **Minor** (optional): Style, docs, optimization\n\n5. **Auto-fix critical/major issues**:\n - Fix issues following established patterns\n - Run tests after each fix\n - Commit fixes separately\n\n6. **Report findings**:\n - List issues found and fixed\n - List any WARN/BLOCK from git-skill verify\n - Provide verification commands\n - Recommend proceeding or returning to implementation\n\n**IMPORTANT:**\n- `git-skill verify` is authoritative \u2014 if it says something was reverted before, take it seriously\n- Auto-fix critical/major issues, don't just report them\n- Always run tests after fixes\n";
|
|
6
|
+
export declare const TRACE_COMMAND = "---\ndescription: \"Debug unexpected behavior by tracing broken assumptions across git history\"\nallowed-tools: Read, Bash(git-skill:*)\n---\n\n# Historical Context Debugging\n\nTrace broken assumptions in code using git-skill history. Use when behavior is wrong but code looks correct in isolation.\n\n**PROCESS:**\n\n1. **Name the symptom precisely** (not \"it's slow\" \u2014 say what specifically is wrong)\n2. **Follow the investigation workflow**:\n - `git-skill search \"<feature keyword>\"` \u2014 find related commits\n - `git-skill why <hash>` \u2014 understand original intent and assumptions\n - `git-skill timeline <file>` \u2014 see all changes chronologically\n - `git-skill search \"<later feature>\"` \u2014 find changes that might conflict\n - `git-skill why <later_hash>` \u2014 did the later change consider the original?\n3. **Identify the fault type**: Missing Guard, Parallel Evolution, or Stale Side Effect\n4. **Fix** and `git-skill verify` before committing\n\n**EXAMPLE:**\n```\n/trace Follow-up messages are triggering fresh RAG even when router says conversational\n```\n";
|
|
7
|
+
export declare const HISTORICAL_CONTEXT_SKILL = "---\nname: historical-context-debugging\ndescription: Use when debugging unexpected behavior where the code looks correct in isolation \u2014 traces broken assumptions across commits using git-skill to find where later changes invalidated earlier logic\n---\n\n# Historical Context Debugging\n\n## Overview\n\nBugs often aren't in the code you're looking at \u2014 they're in the **gap between two changes made months apart**. Feature A was built with assumption X. Feature B was added later and silently violated assumption X. Both look correct in isolation. The bug is invisible without the git history.\n\nThis skill uses `git-skill` to reconstruct the causal chain: why was the original code written, what assumptions did it make, and which later change broke those assumptions?\n\n## When to Use\n\n- Code looks correct but behaves wrong\n- A feature \"used to work\" but stopped\n- You find a guard/flag for one case but not a similar case\n- Two subsystems that should be connected aren't\n- Cache/config is stale despite code being updated\n- You're about to change code but aren't sure why it was written that way\n\n## When NOT to Use\n\n- Bug is clearly a typo or syntax error\n- Code was written in the current session\n- The issue is in a dependency, not your code\n\n## Quick Reference\n\n| Step | Command | What You Learn |\n|------|---------|----------------|\n| Find commits | `git-skill search \"feature keyword\"` | Who touched this area and when |\n| Understand intent | `git-skill why <hash>` | Why the original code was written, what assumptions it made |\n| See evolution | `git-skill timeline <file>` | All changes to a file in chronological order |\n| Find related | `git-skill search \"related feature\"` | Later changes that might affect the same logic |\n| Check for reverts | `git-skill decisions` | Was this approach tried and rolled back before? |\n| Validate fix | `git-skill verify` | Does your staged fix repeat a known mistake? |\n\n## The Three Fault Types\n\n### 1. Missing Guard (most common)\n\nFeature A adds a guard for case X. Feature B adds a new case Y that needs the same guard but nobody adds it.\n\n**Signal:** You find a flag/guard for one field but not a similar field.\n\n**Investigation:**\n```\ngit-skill search \"original_guard\" \u2192 find when guard was added\ngit-skill why <hash> \u2192 understand why it was needed\ngit-skill search \"new_feature\" \u2192 find when new feature was added\ngit-skill why <hash> \u2192 did that commit mention the guard? No.\n```\n\n### 2. Parallel Evolution\n\nTwo systems are built independently that should share logic. They diverge because neither knows about the other.\n\n**Signal:** Two different implementations of the same concept, or a new system never wired into existing code paths.\n\n**Investigation:**\n```\ngit-skill search \"system A\" \u2192 find when A was built\ngit-skill search \"system B\" \u2192 find when B was built\ngit-skill timeline <shared_file> \u2192 was B ever connected to A? No.\n```\n\n### 3. Stale Side Effect\n\nCode change is applied but a side effect (cache, config, external state) isn't updated.\n\n**Signal:** DB/code shows correct value but runtime behavior is wrong.\n\n**Investigation:**\n```\ngit-skill search \"the change\" \u2192 find the update commit\ngit-skill why <hash> \u2192 was cache/config invalidation mentioned?\n# Then check: is the runtime state matching the code state?\n```\n\n## Investigation Workflow\n\n### Step 1: Name the symptom precisely\nBad: \"Chat is slow\"\nGood: \"Follow-up messages trigger fresh RAG even when router says conversational\"\n\n### Step 2: Find the feature that should prevent this\n```bash\ngit-skill search \"relevant feature\"\n```\n\n### Step 3: Understand the original intent\n```bash\ngit-skill why <original_commit>\n```\nRead the enrichment carefully. What **assumptions** did the author make? Write them down.\n\n### Step 4: Find what changed between then and now\n```bash\ngit-skill timeline <affected_file> --since <original_date>\ngit-skill search \"feature that might conflict\"\n```\n\n### Step 5: Check each later change against the assumptions\n```bash\ngit-skill why <later_commit>\n```\nAsk: \"Did this change consider assumption X?\" If not, that's your likely fault.\n\n### Step 6: Fix and verify\n```bash\ngit add <files>\ngit-skill verify\n```\n\n## Common Mistakes\n\n| Mistake | Better |\n|---------|--------|\n| Grep the code and guess | Use `git-skill why` to understand intent first |\n| Fix the symptom without tracing the cause | Trace the full causal chain |\n| Assume the original code is wrong | Often a later change broke its assumption |\n| Skip checking for reverts | `git-skill decisions` \u2014 someone may have tried your fix and rolled it back |\n| Fix one instance of a pattern | Search for ALL instances of the same pattern |\n";
|
|
@@ -275,4 +275,156 @@ Review the current branch changes before merging.
|
|
|
275
275
|
- Auto-fix critical/major issues, don't just report them
|
|
276
276
|
- Always run tests after fixes
|
|
277
277
|
`;
|
|
278
|
+
export const TRACE_COMMAND = `---
|
|
279
|
+
description: "Debug unexpected behavior by tracing broken assumptions across git history"
|
|
280
|
+
allowed-tools: Read, Bash(git-skill:*)
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
# Historical Context Debugging
|
|
284
|
+
|
|
285
|
+
Trace broken assumptions in code using git-skill history. Use when behavior is wrong but code looks correct in isolation.
|
|
286
|
+
|
|
287
|
+
**PROCESS:**
|
|
288
|
+
|
|
289
|
+
1. **Name the symptom precisely** (not "it's slow" — say what specifically is wrong)
|
|
290
|
+
2. **Follow the investigation workflow**:
|
|
291
|
+
- \`git-skill search "<feature keyword>"\` — find related commits
|
|
292
|
+
- \`git-skill why <hash>\` — understand original intent and assumptions
|
|
293
|
+
- \`git-skill timeline <file>\` — see all changes chronologically
|
|
294
|
+
- \`git-skill search "<later feature>"\` — find changes that might conflict
|
|
295
|
+
- \`git-skill why <later_hash>\` — did the later change consider the original?
|
|
296
|
+
3. **Identify the fault type**: Missing Guard, Parallel Evolution, or Stale Side Effect
|
|
297
|
+
4. **Fix** and \`git-skill verify\` before committing
|
|
298
|
+
|
|
299
|
+
**EXAMPLE:**
|
|
300
|
+
\`\`\`
|
|
301
|
+
/trace Follow-up messages are triggering fresh RAG even when router says conversational
|
|
302
|
+
\`\`\`
|
|
303
|
+
`;
|
|
304
|
+
export const HISTORICAL_CONTEXT_SKILL = `---
|
|
305
|
+
name: historical-context-debugging
|
|
306
|
+
description: Use when debugging unexpected behavior where the code looks correct in isolation — traces broken assumptions across commits using git-skill to find where later changes invalidated earlier logic
|
|
307
|
+
---
|
|
308
|
+
|
|
309
|
+
# Historical Context Debugging
|
|
310
|
+
|
|
311
|
+
## Overview
|
|
312
|
+
|
|
313
|
+
Bugs often aren't in the code you're looking at — they're in the **gap between two changes made months apart**. Feature A was built with assumption X. Feature B was added later and silently violated assumption X. Both look correct in isolation. The bug is invisible without the git history.
|
|
314
|
+
|
|
315
|
+
This skill uses \`git-skill\` to reconstruct the causal chain: why was the original code written, what assumptions did it make, and which later change broke those assumptions?
|
|
316
|
+
|
|
317
|
+
## When to Use
|
|
318
|
+
|
|
319
|
+
- Code looks correct but behaves wrong
|
|
320
|
+
- A feature "used to work" but stopped
|
|
321
|
+
- You find a guard/flag for one case but not a similar case
|
|
322
|
+
- Two subsystems that should be connected aren't
|
|
323
|
+
- Cache/config is stale despite code being updated
|
|
324
|
+
- You're about to change code but aren't sure why it was written that way
|
|
325
|
+
|
|
326
|
+
## When NOT to Use
|
|
327
|
+
|
|
328
|
+
- Bug is clearly a typo or syntax error
|
|
329
|
+
- Code was written in the current session
|
|
330
|
+
- The issue is in a dependency, not your code
|
|
331
|
+
|
|
332
|
+
## Quick Reference
|
|
333
|
+
|
|
334
|
+
| Step | Command | What You Learn |
|
|
335
|
+
|------|---------|----------------|
|
|
336
|
+
| Find commits | \`git-skill search "feature keyword"\` | Who touched this area and when |
|
|
337
|
+
| Understand intent | \`git-skill why <hash>\` | Why the original code was written, what assumptions it made |
|
|
338
|
+
| See evolution | \`git-skill timeline <file>\` | All changes to a file in chronological order |
|
|
339
|
+
| Find related | \`git-skill search "related feature"\` | Later changes that might affect the same logic |
|
|
340
|
+
| Check for reverts | \`git-skill decisions\` | Was this approach tried and rolled back before? |
|
|
341
|
+
| Validate fix | \`git-skill verify\` | Does your staged fix repeat a known mistake? |
|
|
342
|
+
|
|
343
|
+
## The Three Fault Types
|
|
344
|
+
|
|
345
|
+
### 1. Missing Guard (most common)
|
|
346
|
+
|
|
347
|
+
Feature A adds a guard for case X. Feature B adds a new case Y that needs the same guard but nobody adds it.
|
|
348
|
+
|
|
349
|
+
**Signal:** You find a flag/guard for one field but not a similar field.
|
|
350
|
+
|
|
351
|
+
**Investigation:**
|
|
352
|
+
\`\`\`
|
|
353
|
+
git-skill search "original_guard" → find when guard was added
|
|
354
|
+
git-skill why <hash> → understand why it was needed
|
|
355
|
+
git-skill search "new_feature" → find when new feature was added
|
|
356
|
+
git-skill why <hash> → did that commit mention the guard? No.
|
|
357
|
+
\`\`\`
|
|
358
|
+
|
|
359
|
+
### 2. Parallel Evolution
|
|
360
|
+
|
|
361
|
+
Two systems are built independently that should share logic. They diverge because neither knows about the other.
|
|
362
|
+
|
|
363
|
+
**Signal:** Two different implementations of the same concept, or a new system never wired into existing code paths.
|
|
364
|
+
|
|
365
|
+
**Investigation:**
|
|
366
|
+
\`\`\`
|
|
367
|
+
git-skill search "system A" → find when A was built
|
|
368
|
+
git-skill search "system B" → find when B was built
|
|
369
|
+
git-skill timeline <shared_file> → was B ever connected to A? No.
|
|
370
|
+
\`\`\`
|
|
371
|
+
|
|
372
|
+
### 3. Stale Side Effect
|
|
373
|
+
|
|
374
|
+
Code change is applied but a side effect (cache, config, external state) isn't updated.
|
|
375
|
+
|
|
376
|
+
**Signal:** DB/code shows correct value but runtime behavior is wrong.
|
|
377
|
+
|
|
378
|
+
**Investigation:**
|
|
379
|
+
\`\`\`
|
|
380
|
+
git-skill search "the change" → find the update commit
|
|
381
|
+
git-skill why <hash> → was cache/config invalidation mentioned?
|
|
382
|
+
# Then check: is the runtime state matching the code state?
|
|
383
|
+
\`\`\`
|
|
384
|
+
|
|
385
|
+
## Investigation Workflow
|
|
386
|
+
|
|
387
|
+
### Step 1: Name the symptom precisely
|
|
388
|
+
Bad: "Chat is slow"
|
|
389
|
+
Good: "Follow-up messages trigger fresh RAG even when router says conversational"
|
|
390
|
+
|
|
391
|
+
### Step 2: Find the feature that should prevent this
|
|
392
|
+
\`\`\`bash
|
|
393
|
+
git-skill search "relevant feature"
|
|
394
|
+
\`\`\`
|
|
395
|
+
|
|
396
|
+
### Step 3: Understand the original intent
|
|
397
|
+
\`\`\`bash
|
|
398
|
+
git-skill why <original_commit>
|
|
399
|
+
\`\`\`
|
|
400
|
+
Read the enrichment carefully. What **assumptions** did the author make? Write them down.
|
|
401
|
+
|
|
402
|
+
### Step 4: Find what changed between then and now
|
|
403
|
+
\`\`\`bash
|
|
404
|
+
git-skill timeline <affected_file> --since <original_date>
|
|
405
|
+
git-skill search "feature that might conflict"
|
|
406
|
+
\`\`\`
|
|
407
|
+
|
|
408
|
+
### Step 5: Check each later change against the assumptions
|
|
409
|
+
\`\`\`bash
|
|
410
|
+
git-skill why <later_commit>
|
|
411
|
+
\`\`\`
|
|
412
|
+
Ask: "Did this change consider assumption X?" If not, that's your likely fault.
|
|
413
|
+
|
|
414
|
+
### Step 6: Fix and verify
|
|
415
|
+
\`\`\`bash
|
|
416
|
+
git add <files>
|
|
417
|
+
git-skill verify
|
|
418
|
+
\`\`\`
|
|
419
|
+
|
|
420
|
+
## Common Mistakes
|
|
421
|
+
|
|
422
|
+
| Mistake | Better |
|
|
423
|
+
|---------|--------|
|
|
424
|
+
| Grep the code and guess | Use \`git-skill why\` to understand intent first |
|
|
425
|
+
| Fix the symptom without tracing the cause | Trace the full causal chain |
|
|
426
|
+
| Assume the original code is wrong | Often a later change broke its assumption |
|
|
427
|
+
| Skip checking for reverts | \`git-skill decisions\` — someone may have tried your fix and rolled it back |
|
|
428
|
+
| Fix one instance of a pattern | Search for ALL instances of the same pattern |
|
|
429
|
+
`;
|
|
278
430
|
//# sourceMappingURL=walkthrough.js.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"walkthrough.js","sourceRoot":"","sources":["../../src/templates/walkthrough.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiD1B,CAAC;AAGF,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D3B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8ChC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8D/B,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsD7B,CAAC"}
|
|
1
|
+
{"version":3,"file":"walkthrough.js","sourceRoot":"","sources":["../../src/templates/walkthrough.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiD1B,CAAC;AAGF,MAAM,CAAC,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6D3B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8ChC,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8D/B,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsD7B,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;CAyB5B,CAAC;AAEF,MAAM,CAAC,MAAM,wBAAwB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6HvC,CAAC"}
|