sdtk-kit 0.3.0

package/assets/toolkit/toolkit/templates/docs/specs/BA_SPEC_TEMPLATE.md

@@ -0,0 +1,139 @@
+# BA SPEC: {{FEATURE_KEY}} ({{FEATURE_NAME}})
+
+**Document ID:** BA_SPEC_{{FEATURE_KEY}}
+**Version:** 1.0.0
+**Date:** {{DATE}}
+**Author:** BA Agent
+**Status:** DRAFT - Ready for PM Review
+
+---
+
+## Abbreviations
+
+| No | Abbreviation | Meaning |
+| ---: | --- | --- |
+| 1 | API | Application Programming Interface |
+| 2 | DB | Database |
+| 3 | UI | User Interface |
+| 4 | UX | User Experience |
+| 5 | BR | Business Rule |
+| 6 | UC | Use Case |
+| 7 | AC | Acceptance Criteria |
+| 8 | NFR | Non-Functional Requirement |
+| 9 | OQ | Open Question |
+| 10 | REQ | Requirement |
+
+---
+
+## 1. DOMAIN ANALYSIS
+
+### 1.1 Domain Glossary
+
+| No | Term | Definition | Example |
+| ---: | --- | --- | --- |
+| 1 | TBD | TBD | TBD |
+
+### 1.2 Business Rules
+
+| No | Rule ID | Rule Description | Type | Related REQ |
+| ---: | --- | --- | --- | --- |
+| 1 | BR-01 | TBD | Mandatory | REQ-01 |
+
+### 1.3 Non-Functional Requirements
+
+| No | NFR ID | Category | Requirement | Target |
+| ---: | --- | --- | --- | --- |
+| 1 | NFR-01 | Performance | TBD | TBD |
+
+---
+
+## 2. USE CASES
+
+| No | UC ID | Use Case Name | Primary Actor | Related REQ |
+| ---: | --- | --- | --- | --- |
+| 1 | UC-01 | TBD | TBD | REQ-01 |
+
+---
+
+## 3. DATA MODEL (Logical)
+
+| No | Entity | Description | Key Fields |
+| ---: | --- | --- | --- |
+| 1 | TBD | TBD | TBD |
+
+---
+
+## 4. CONTRACTS SUMMARY
+
+### 4.1 API Endpoints (High-level)
+
+| No | Endpoint | Method | Purpose | Related UC |
+| ---: | --- | --- | --- | --- |
+| 1 | `/api/v1/...` | GET | TBD | UC-01 |
+
+### 4.2 UI Screens (if applicable)
+
+| No | Screen ID | Screen Name | Purpose | Related UC |
+| ---: | --- | --- | --- | --- |
+| 1 | SCR-01 | TBD | TBD | UC-01 |
+
+### 4.3 Acceptance Criteria (high-level)
+
+| No | AC ID | Acceptance Criteria | Related UC | Related BR |
+| ---: | --- | --- | --- | --- |
+| 1 | AC-01-01 | TBD | UC-01 | BR-01 |
+
+---
+
+## 5. RISKS & OPEN QUESTIONS
+
+### 5.1 Risks
+
+| No | Risk ID | Risk | Probability | Impact | Mitigation |
+| ---: | --- | --- | --- | --- | --- |
+| 1 | R-01 | TBD | Medium | Medium | TBD |
+
+### 5.2 Open Questions
+
+| No | Q-ID | Question | Type | Priority | Decision Owner (PM/User) | Status (OPEN/RESOLVED) | Notes/Options | Resolution |
+| ---: | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | OQ-01 | TBD | Business | High | PM | OPEN | TBD | TBD |
+
+---
+
+## 6. TRACEABILITY SUMMARY
+
+| No | REQ ID | Use Cases | Business Rules | Acceptance Criteria | Status |
+| ---: | --- | --- | --- | --- | --- |
+| 1 | REQ-01 | UC-01 | BR-01 | AC-01-01 | COVERED |
+
+---
+
+## 7. HANDOFF
+
+HANDOFF TO PM:
+`@pm BA_SPEC_{{FEATURE_KEY}} is ready. Please create PRD_{{FEATURE_KEY}}.md + BACKLOG_{{FEATURE_KEY}}.md`
+
+Next:
+`@arch please design architecture for {{FEATURE_KEY}} after PM review`
+
+NOTE:
+`@pm please resolve Open Questions (OQ-xx) above; if any cannot be resolved from existing docs, please confirm with the user (final stakeholder).`
+
+---
+
+## APPENDIX A: Source Requirements (Original VI/JP) - keep as-is
+
+If the input requirements were provided in Vietnamese/Japanese, paste them here unchanged.
+
+## APPENDIX B: English Translation (of Appendix A)
+
+Provide an English translation of Appendix A (literal, for traceability).
+
+---
+
+## Document History
+
+| No | Version | Date | Author | Changes |
+| ---: | --- | --- | --- | --- |
+| 1 | 1.0.0 | {{DATE}} | BA Agent | Initial template-based version |

package/assets/toolkit/toolkit/templates/docs/specs/FLOW_ACTION_SPEC_CREATION_RULES.md

@@ -0,0 +1,136 @@
+# Flow Action Spec Creation Rules for AI Agents
+
+This document defines reusable rules for creating and updating screen flow-action specifications
+(for example `docs/specs/*_FLOW_ACTION_SPEC.md`).
+
+## 1. Scope and Goal
+
+- Produce a screen-level specification that is traceable from BA/ARCH to FE/BE implementation.
+- Keep one source of truth for:
+  - screen flow
+  - UI items and actions
+  - API calls per action
+  - screen-to-API mapping
+- Keep documentation implementation-aware and review-friendly.
+
+## 2. Mandatory Document Structure
+
+A flow-action spec should include, at minimum:
+
+1. `Abbreviations`
+2. `Feature overview`
+3. `Screen flow action` (with PlantUML)
+4. `Screen layout spec by flow action`
+5. `System processing flow`
+6. `Open questions`
+7. `Screen - API mapping`
+8. `Document history`
+
+If a section is not in scope, keep the section and mark explicitly as `N/A` with reason.
+
+## 3. Table Standards
+
+- Every table must include a `No` column (sequential numbering).
+- Use stable headers for action tables:
+  - `No | JP Item Name | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
+- Use stable headers for API mapping tables:
+  - `No | Trigger/When | UI item (No / JP Item Name) | API to call | Data usage / Notes`
+- Use stable headers for screen mapping:
+  - `No | Screen (section) | Screen ID | Read/Search APIs | Write APIs | Notes / Q&A refs`
+- Table rows must keep column count consistent with the header (no broken or merged rows).
+- Avoid single-line merged content that collapses multiple logical items into one table row.
+
+### 3.1 Language and Encoding Standards (EN Artifacts)
+
+- For EN artifacts (`docs/en/**` or explicitly requested EN version), narrative text must be English.
+- JP labels can remain only in JP-specific fields/columns (`JP Item Name`, `項目名`, source captions).
+- Do not leave mixed-language fragments in one sentence/cell (for example VI+EN mixed text).
+- If original VI/JP text is required for traceability, keep it in a clearly marked appendix block (`Original Text`), then provide EN translation.
+- Save files as UTF-8 and avoid mojibake/broken glyphs (`�`, `ↁE`, garbled sequences).
+- Keep canonical terminology stable across documents (for example: `bukken`, `sagyo`, `customer employee`).
+
+### 3.2 Markdown Structure Hygiene
+
+- Keep each heading on its own line; do not concatenate multiple headings/sections on one line.
+- Keep metadata blocks (`Information`, `Note`, `Behavior notes`) as structured bullet blocks, not single compressed lines.
+- Keep image, table, and separator (`---`) boundaries explicit to preserve parser/render stability.
+
+## 4. Item Numbering and Duplication Rules
+
+- Use one numbering mode only: `global across document`.
+- Number values must increase across all action tables in the document.
+- Avoid duplicate item descriptions for the same UI control across screens unless behavior differs.
+- If duplicate number is intentional (rare), annotate reason in `Note`.
+
+## 5. Screen Section Rules
+
+For each screen section:
+
+- Provide metadata:
+  - official screen name
+  - Screen ID
+  - design source URL (for example Figma)
+- Embed one representative image per screen.
+- Provide one action table.
+- Provide one API mapping table.
+- If a screen has dialogs, create explicit dialog sub-sections with their own tables and API mapping.
+
+## 6. API Traceability Rules
+
+- Every actionable UI event that changes state must map to a write API.
+- Every data-loading UI event must map to a read/search API.
+- If one endpoint serves multiple actions (initial load, search, refresh), state this explicitly.
+- If no API is called for an action, state `No API` and explain why.
+
+## 7. PlantUML Rules for Screen Flow
+
+- Use valid PlantUML syntax and renderability checks before handoff.
+- Use `\\n` for multi-line labels in nodes.
+- Keep diagram at navigation/action level (not low-level SQL or backend internals).
+- Ensure screen names in PlantUML match section names in layout spec.
+
+## 8. Data Source and Asset Rules
+
+- Prioritize source order:
+  1. Confirmed design source (for example Figma)
+  2. Confirmed requirement files (Excel/spec)
+  3. User-provided screenshots
+- Store images in repository-relative paths.
+- Do not keep temporary local absolute paths in markdown.
+
+## 9. Consistency with Other Specs
+
+- Align terms with:
+  - BA spec glossary
+  - API endpoints spec
+  - Database spec
+- If terminology differs across docs, raise an open question and add a temporary mapping note.
+- Keep endpoint paths in flow-action spec consistent with API endpoint spec.
+
+## 10. Open Questions and Uncertainty Handling
+
+- Capture unresolved items in `Open questions` table.
+- Do not invent UI behavior or API contracts when source is ambiguous.
+- Mark uncertain mappings as `Draft` and include impacted files/sections.
+
+## 11. Change Management
+
+- On each update:
+  - update impacted screen sections
+  - update API mapping tables
+  - update screen-to-API mapping summary
+  - append one row in document history
+- Never overwrite past history rows.
+
+## 12. Final Checklist Before Handoff
+
+- PlantUML renders successfully.
+- All mandatory sections exist.
+- All tables include `No`.
+- Numbering is global across the document (no resets).
+- No broken image links.
+- Screen/API mappings are consistent with `*_ENDPOINTS.md`.
+- Open questions are explicit and traceable.
+- For EN artifact: no leftover VI text outside allowed `Original Text` appendix blocks.
+- No mojibake/encoding corruption markers.
+- Headings/tables are structurally clean (no merged lines that break readability/traceability).

package/assets/toolkit/toolkit/templates/docs/specs/FLOW_ACTION_SPEC_TEMPLATE.md

@@ -0,0 +1,160 @@
+# {{FEATURE_NAME}} - Screen Flow Action Specification
+
+**Document ID:** {{FEATURE_KEY}}_FLOW_ACTION_SPEC
+**Version:** 1.0.0
+**Date:** {{DATE}}
+**Author:** ARCH Agent
+**Status:** DRAFT
+**Related Specs:** `docs/specs/BA_SPEC_{{FEATURE_KEY}}.md`, `docs/api/{{FEATURE_KEY}}_ENDPOINTS.md`, `docs/database/DATABASE_SPEC_{{FEATURE_KEY}}.md`
+
+---
+
+## Abbreviations
+
+| No | Abbreviation | Meaning |
+| ---: | --- | --- |
+| 1 | UI | User Interface |
+| 2 | UX | User Experience |
+| 3 | API | Application Programming Interface |
+| 4 | FE | Frontend |
+| 5 | BE | Backend |
+| 6 | OQ | Open Question |
+
+---
+
+## 1) Feature overview
+
+### 1.1 Background and user needs
+- TBD
+
+### 1.2 Target features in scope
+- TBD
+
+### 1.3 Implementation direction
+- TBD
+
+---
+
+## 2) Screen flow action
+
+### 2.1 Flow diagram (PlantUML)
+
+```plantuml
+@startuml
+left to right direction
+skinparam shadowing false
+skinparam packageStyle rectangle
+
+rectangle "Screen A" as A
+rectangle "Screen B" as B
+rectangle "Dialog C" as C
+
+A --> B : action
+B --> C : open dialog
+@enduml
+```
+
+### 2.2 Mapping to major screens
+
+| No | Screen Group | Screen Name | Screen ID | Notes |
+| ---: | --- | --- | --- | --- |
+| 1 | Main | Screen A | SCR-01 | TBD |
+| 2 | Main | Screen B | SCR-02 | TBD |
+
+---
+
+## 3) Screen layout spec by flow action
+
+> Standard item table format:
+> `No | JP Item Name | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note`
+
+### 3.1 Screen A
+
+Information:
+- JP: TBD
+- Screen ID: SCR-01
+- Figma URL: TBD
+
+Screen image:
+![3.1 Screen A](assets/{{FEATURE_SNAKE}}/screens/screen_3_1_screen_a.png)
+
+| No | JP Item Name | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
+| ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | Item A (JP) | Item A | Button | - | - | - | - | Click | TBD | TBD |
+| 2 | Item B (JP) | Item B | Input | string | column_a | 100 | empty | Input | TBD | TBD |
+
+#### API Mapping (Draft)
+
+| No | Trigger/When | UI item (No / JP Item Name) | API to call | Data usage / Notes |
+| ---: | --- | --- | --- | --- |
+| 1 | Initial load | Main area | `GET /api/...` | Load initial dataset |
+| 2 | Click search | No 1 | `POST /api/.../search` | Refresh grid |
+
+---
+
+### 3.2 Screen B
+
+Information:
+- JP: TBD
+- Screen ID: SCR-02
+- Figma URL: TBD
+
+Screen image:
+![3.2 Screen B](assets/{{FEATURE_SNAKE}}/screens/screen_3_2_screen_b.png)
+
+| No | JP Item Name | Item Name | Item Type | Attribute | DB Column | Size | Default Value | Action | Description | Note |
+| ---: | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 3 | Item C (JP) | Item C | Toggle | boolean | flag_a | - | false | Toggle | TBD | TBD |
+
+#### API Mapping (Draft)
+
+| No | Trigger/When | UI item (No / JP Item Name) | API to call | Data usage / Notes |
+| ---: | --- | --- | --- | --- |
+| 1 | Change mode | No 3 | `POST /api/.../edit/{uuid}` | Persist mode |
+
+---
+
+## 4) System processing flow
+
+### 4.1 Initial load
+1. Validate screen permissions.
+2. Load settings/profile context.
+3. Load main dataset.
+
+### 4.2 Create/Update/Delete flow
+1. Validate request.
+2. Execute write API.
+3. Refresh read dataset.
+
+---
+
+## 5) Notes
+
+- Keep item numbering strategy explicit (`global` or `per-screen`).
+- Do not duplicate item descriptions across screens unless behavior differs.
+
+---
+
+## 6) Open questions
+
+| No | Scope | Question | Impact |
+| ---: | --- | --- | --- |
+| 1 | UI | TBD | TBD |
+| 2 | API | TBD | TBD |
+
+---
+
+## 7) Screen - API Mapping
+
+| No | Screen (section) | Screen ID | Read/Search APIs | Write APIs | Notes / Q&A refs |
+| ---: | --- | --- | --- | --- | --- |
+| 1 | 3.1 Screen A | SCR-01 | `GET /api/...` | `POST /api/...` | TBD |
+| 2 | 3.2 Screen B | SCR-02 | `POST /api/.../search` | `POST /api/.../edit/{uuid}` | TBD |
+
+---
+
+## Document History
+
+| No | Version | Date | Author | Changes |
+| ---: | --- | --- | --- | --- |
+| 1 | 1.0.0 | {{DATE}} | ARCH Agent | Initial template-based version |

package/bin/sdtk.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { run } = require("../src/index");
+
+run(process.argv.slice(2))
+  .then((exitCode) => {
+    process.exitCode = Number.isInteger(exitCode) ? exitCode : 0;
+  })
+  .catch((error) => {
+    console.error(`sdtk: ${error.message}`);
+    process.exitCode =
+      typeof error.exitCode === "number" ? error.exitCode : 4;
+  });

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "sdtk-kit",
+  "version": "0.3.0",
+  "description": "SDTK CLI toolkit for deterministic software documentation workflows",
+  "bin": {
+    "sdtk": "./bin/sdtk.js"
+  },
+  "main": "src/index.js",
+  "type": "commonjs",
+  "files": [
+    "bin/",
+    "src/",
+    "assets/"
+  ],
+  "scripts": {
+    "test": "node -e \"console.log('No tests configured yet')\"",
+    "build:payload": "powershell -ExecutionPolicy Bypass -File scripts/sync-toolkit-assets.ps1 && powershell -ExecutionPolicy Bypass -File scripts/build-toolkit-manifest.ps1",
+    "verify:payload": "node -e \"require('./src/lib/toolkit-payload').verify()\"",
+    "pack:smoke": "npm pack --dry-run",
+    "pack:release": "npm pack",
+    "prepublishOnly": "node -e \"require('./src/lib/toolkit-payload').verify()\""
+  },
+  "engines": {
+    "node": ">=18.13.0"
+  },
+  "keywords": [
+    "sdtk",
+    "cli",
+    "documentation",
+    "toolkit",
+    "dockkit"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/codexsdtk/sdtk-toolkit.git",
+    "directory": "distribution/sdtk-cli"
+  },
+  "homepage": "https://sdtk.dev",
+  "bugs": {
+    "url": "https://github.com/codexsdtk/sdtk-toolkit/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}
+

package/src/commands/auth.js

@@ -0,0 +1,85 @@
+"use strict";
+
+const { clearAuthState, readAuthState, writeAuthState } = require("../lib/state");
+const { parseFlags } = require("../lib/args");
+const { checkRepoAccess } = require("../lib/github-access");
+const { ValidationError } = require("../lib/errors");
+
+const FLAG_DEFS = {
+  token: { type: "string" },
+  status: { type: "boolean" },
+  logout: { type: "boolean" },
+  verify: { type: "boolean" },
+};
+
+/**
+ * Redact a token for safe display (show first 4 chars only).
+ */
+function redactToken(token) {
+  if (!token || token.length < 8) return "****";
+  return token.slice(0, 4) + "****";
+}
+
+async function cmdAuth(args) {
+  const { flags } = parseFlags(args, FLAG_DEFS);
+
+  if (flags.status) {
+    const state = readAuthState();
+    if (!state.authenticated) {
+      console.log("Auth status: not authenticated");
+      console.log('Run "sdtk auth --token <value>" to authenticate.');
+      return 1;
+    }
+    console.log("Auth status: authenticated");
+    console.log(`Token: ${redactToken(state.token)}`);
+    return 0;
+  }
+
+  if (flags.logout) {
+    clearAuthState();
+    console.log("Auth state cleared.");
+    return 0;
+  }
+
+  // Process --token first, then optionally --verify in the same invocation.
+  // This supports: sdtk auth --token <value> --verify
+  if (flags.token) {
+    const { path: authFile, hardened } = writeAuthState(flags.token);
+    if (hardened) {
+      console.log("Token stored securely.");
+    } else {
+      console.log("Token stored (file permission hardening was not applied).");
+    }
+    console.log(`Auth file: ${authFile}`);
+
+    if (flags.verify) {
+      console.log("");
+      console.log("Verifying repository access...");
+      const result = await checkRepoAccess(flags.token);
+      console.log(result.message);
+      return result.hasAccess ? 0 : 1;
+    }
+
+    console.log('Run "sdtk auth --verify" to check repository access.');
+    return 0;
+  }
+
+  if (flags.verify) {
+    const state = readAuthState();
+    if (!state.authenticated) {
+      console.log("Not authenticated. Store a token first with --token.");
+      return 1;
+    }
+    const result = await checkRepoAccess(state.token);
+    console.log(result.message);
+    return result.hasAccess ? 0 : 1;
+  }
+
+  throw new ValidationError(
+    "Usage: sdtk auth --token <value> [--verify] | --status | --logout"
+  );
+}
+
+module.exports = {
+  cmdAuth,
+};