kenaz 0.3.18 → 0.3.20

package/core/dev/scripts/matrix/CLI_README.md

@@ -1,214 +0,0 @@
-# matrix CLI - Command Line Tool
-
-`matrix` is a command-line tool for managing `.matrix` format files. It provides CRUD operations (Create, Read, Update, Delete) for working with matrix rules.
-
-## Installation
-
-```bash
-# Install dependencies
-npm install
-
-# Build the CLI
-npm run build
-
-# Link CLI globally (optional)
-npm link
-```
-
-After installation, you can use the `matrix` command anywhere in your terminal.
-
-## Commands
-
-### 1. Create - Create a new .matrix file
-
-Creates a new `.matrix` file with specified metadata.
-
-**Syntax:**
-```bash
-matrix create <file> [options]
-```
-
-**Options:**
-- `-v, --version <version>` - Version number (e.g., 1.0.0)
-- `-c, --category <category>` - Category (T/M/R/P or custom)
-- `-i, --interactive` - Use interactive mode with prompts
-
-**Examples:**
-```bash
-# Create with parameters
-matrix create tasks.matrix -v 1.0.0 -c T
-
-# Create with interactive mode
-matrix create memory.matrix -i
-
-# Create project status file
-matrix create project_status --version 2.0.0 --category P
-```
-
-**Output:**
-- Creates a new `.matrix` file with `@meta`, `@index`, and `@data` sections
-- Auto-appends `.matrix` extension if not provided
-
----
-
-### 2. Read - Read and display .matrix file
-
-Reads a `.matrix` file and displays its content with level-based filtering.
-
-**Syntax:**
-```bash
-matrix read <file> [options]
-```
-
-**Options:**
-- `-l, --level <level>` - Display level (default: 3)
-  - `1` - Overview only (@meta + @index)
-  - `2` - Recent 10 records
-  - `3` - All records
-
-**Examples:**
-```bash
-# Read all records (default)
-matrix read tasks.matrix
-
-# Read overview only
-matrix read tasks.matrix --level 1
-
-# Read recent 10 records
-matrix read memory.matrix -l 2
-```
-
-**Output:**
-- ✓ Green checkmark for success
-- Formatted display with color-coded fields
-- Statistics and record details
-
----
-
-### 3. Update - Update a rule
-
-Updates a specific rule in a `.matrix` file and auto-updates `@index` statistics.
-
-**Syntax:**
-```bash
-matrix update <file> <rule-id> [options]
-```
-
-**Options:**
-- `-f, --field <field>` - Field name to update
-- `-v, --value <value>` - New value for the field
-- `-i, --interactive` - Use interactive mode with field selection
-
-**Examples:**
-```bash
-# Update with parameters
-matrix update tasks.matrix TASK_001 -f status -v completed
-
-# Update with interactive mode
-matrix update tasks.matrix TASK_002 -i
-
-# Update priority field
-matrix update memory.matrix MEM_005 --field priority --value high
-```
-
-**Features:**
-- Auto-detects value types (boolean, number, array, string)
-- Updates `@index.upd` timestamp automatically
-- Interactive mode shows existing fields for easy selection
-- Supports adding new fields
-
----
-
-### 4. Delete - Delete a rule
-
-Deletes a rule from a `.matrix` file and auto-updates `@index` statistics.
-
-**Syntax:**
-```bash
-matrix delete <file> <rule-id> [options]
-```
-
-**Options:**
-- `-f, --force` - Skip confirmation prompt
-
-**Examples:**
-```bash
-# Delete with confirmation
-matrix delete tasks.matrix TASK_001
-
-# Delete without confirmation
-matrix delete tasks.matrix TASK_002 -f
-
-# Force delete
-matrix delete memory.matrix MEM_OLD --force
-```
-
-**Features:**
-- Confirmation prompt before deletion (unless `--force`)
-- Auto-updates `@index.n` (rule count)
-- Auto-updates `@index.upd` timestamp
-- Shows remaining rule count after deletion
-
----
-
-## Error Handling
-
-All commands provide friendly error messages:
-
-- ✗ **File not found**: Suggests using `matrix create`
-- ✗ **Rule not found**: Suggests using `matrix read` to list rules
-- ✗ **Parse error**: Shows error message with line and column numbers
-- ✗ **Invalid level**: Suggests valid level values (1, 2, 3)
-
-## Color Codes
-
-- 🟢 **Green ✓** - Success
-- 🔴 **Red ✗** - Error
-- 🔵 **Blue ℹ** - Info
-- 🟡 **Yellow ⚠** - Warning
-- 🔵 **Cyan** - Section headers
-
-## Global Help
-
-```bash
-# Show all commands
-matrix --help
-
-# Show command-specific help
-matrix create --help
-matrix read --help
-matrix update --help
-matrix delete --help
-```
-
-## Development
-
-```bash
-# Run tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Build TypeScript
-npm run build
-```
-
-## File Format
-
-All commands work with `.matrix` format files:
-
-```
-@meta |v=1.0.0|c=T|
-@index |n=2|upd=2026-02-09 15:21:00|
-@data
-TASK_001|st=P|pr=P0|tl=Implement feature|
-TASK_002|st=C|pr=P1|tl=Fix bug|
-```
-
-## Notes
-
-- The CLI automatically appends `.matrix` extension if not provided
-- All update/delete operations preserve file structure and formatting
-- Interactive mode provides user-friendly prompts for all inputs
-- Value types are auto-detected (boolean, number, array, string)

package/core/dev/scripts/matrix/README.md

@@ -1,310 +0,0 @@
-# .matrix Parser & Serializer
-
-> Node.js/TypeScript library for parsing and serializing .matrix format files
-
-**Version**: 1.0.0
-**Tasks**: TASK_141 (Parser/Serializer), TASK_142 (CLI Tool)
-**Feature**: F-015
-
----
-
-## 📋 Overview
-
-This library provides a complete implementation of the .matrix v1.0 format specification, including:
-
-- **Parser**: Parse .matrix files into JavaScript objects
-- **Serializer**: Serialize JavaScript objects into .matrix format
-- **Validator**: Validate .matrix file syntax with detailed error messages
-- **CLI Tool**: Command-line interface for CRUD operations (create, read, update, delete)
-
----
-
-## 🚀 Installation
-
-```bash
-cd dev/scripts/matrix
-npm install
-
-# Optional: Link CLI globally
-npm link
-```
-
----
-
-## 📖 Usage
-
-### CLI Tool
-
-For command-line operations, see **[CLI_README.md](./CLI_README.md)** for complete documentation.
-
-**Quick Examples**:
-```bash
-# Create a new .matrix file
-matrix create tasks.matrix -v 1.0.0 -c T
-
-# Read file content
-matrix read tasks.matrix --level 2
-
-# Update a rule
-matrix update tasks.matrix TASK_001 -f status -v completed
-
-# Delete a rule
-matrix delete tasks.matrix TASK_002 -f
-```
-
-### Programmatic API
-
-### Basic Example
-
-```typescript
-import { parse, serialize, validate } from '@kenaz/matrix-parser';
-
-// Parse .matrix file
-const content = `# .matrix v1.0
-@meta |v=1.0|c=tasks|t=260207-0530|
-@index |tot=123|c=100|p=15|
-@data
-T121|st=C|p=0|dur=135m|desc=API integration|`;
-
-const result = parse(content);
-if (result.success) {
-  console.log(result.data);
-  // {
-  //   meta: { v: '1.0', c: 'tasks', t: '260207-0530' },
-  //   index: { tot: 123, c: 100, p: 15 },
-  //   data: { records: [...] }
-  // }
-}
-
-// Serialize back to .matrix format
-const serialized = serialize(result.data!);
-console.log(serialized);
-
-// Validate syntax
-const validation = validate(content);
-if (!validation.valid) {
-  console.error(validation.errors);
-}
-```
-
-### Using Classes
-
-```typescript
-import { MatrixParser, MatrixSerializer, MatrixValidator } from '@kenaz/matrix-parser';
-
-// Parser with options
-const parser = new MatrixParser({
-  strict: true,        // Throw error on invalid syntax
-  autoFix: false,      // Automatically fix common errors
-  validateFields: true // Validate field names
-});
-
-const result = parser.parse(content);
-
-// Serializer with options
-const serializer = new MatrixSerializer({
-  pretty: false,          // Add newlines for readability
-  includeComment: true,   // Include comment line
-  comment: '.matrix v1.0' // Custom comment
-});
-
-const output = serializer.serialize(data);
-
-// Validator
-const validator = new MatrixValidator();
-const validation = validator.validate(content);
-```
-
----
-
-## 🔤 Abbreviations
-
-The library automatically handles field abbreviations and value encoding:
-
-### Field Abbreviations (72 fields)
-
-```typescript
-status → st
-priority → p
-created_at → ct
-updated_at → ut
-duration → dur
-description → desc
-dependencies → dep
-// ... and 65 more
-```
-
-### Value Codes (66 codes)
-
-```typescript
-completed → C
-in_progress → P
-pending → D
-P0 → 0
-P1 → 1
-true → 1
-false → 0
-// ... and 59 more
-```
-
-### Timestamp Shortening
-
-```typescript
-2026-02-07T05:30:00Z → 260207-0530
-2026-12-31T23:59:00Z → 261231-2359
-```
-
----
-
-## ✅ Features
-
-### Parser
-
-- ✅ Parse three-layer structure (`@meta`, `@index`, `@data`)
-- ✅ Automatic field name expansion
-- ✅ Automatic value decoding
-- ✅ Support for complex task groups
-- ✅ Type inference (boolean, number, list, etc.)
-- ✅ Friendly error messages with line numbers
-
-### Serializer
-
-- ✅ Serialize JavaScript objects to .matrix format
-- ✅ Automatic field name abbreviation
-- ✅ Automatic value encoding
-- ✅ Timestamp shortening
-- ✅ Lossless round-trip (parse → serialize → parse)
-
-### Validator
-
-- ✅ Detect 10+ syntax error types
-- ✅ Line number and column position
-- ✅ Expected vs actual comparison
-- ✅ Warnings for non-critical issues
-
----
-
-## 🧪 Testing
-
-```bash
-# Run tests
-npm test
-
-# Run tests with coverage
-npm run test:coverage
-
-# Watch mode
-npm run test:watch
-```
-
-**Coverage Target**: > 90%
-
----
-
-## 📚 Documentation
-
-- **Syntax Specification**: `../../design/matrix_format_SYNTAX_BNF.md`
-- **Abbreviations**: `../../design/matrix_format_ABBREVIATIONS.md`
-- **Examples**: `../../design/matrix_format_EXAMPLE_*.matrix`
-
----
-
-## 📝 API Reference
-
-### `parse(content: string, options?: ParseOptions): ParseResult`
-
-Parse .matrix file content.
-
-**Parameters**:
-- `content`: .matrix file content
-- `options`: Parse options
-  - `strict`: Throw error on invalid syntax (default: `true`)
-  - `autoFix`: Automatically fix common errors (default: `false`)
-  - `validateFields`: Validate field names (default: `true`)
-
-**Returns**: `ParseResult`
-```typescript
-{
-  success: boolean;
-  data?: MatrixFile;
-  error?: ParseError;
-}
-```
-
-### `serialize(data: MatrixFile, options?: SerializeOptions): string`
-
-Serialize MatrixFile to .matrix format.
-
-**Parameters**:
-- `data`: MatrixFile object
-- `options`: Serialize options
-  - `pretty`: Add newlines for readability (default: `false`)
-  - `includeComment`: Include comment line (default: `true`)
-  - `comment`: Custom comment (default: `".matrix v1.0"`)
-
-**Returns**: `.matrix` file content
-
-### `validate(content: string): ValidationResult`
-
-Validate .matrix file syntax.
-
-**Parameters**:
-- `content`: .matrix file content
-
-**Returns**: `ValidationResult`
-```typescript
-{
-  valid: boolean;
-  errors: ParseError[];
-  warnings: ParseError[];
-}
-```
-
----
-
-## 🔧 Error Codes
-
-| Code | Description | Severity |
-|------|-------------|----------|
-| E000 | Empty file | Error |
-| E001 | Missing required section | Error |
-| E002 | Invalid section order | Error |
-| E003 | Missing delimiters | Error |
-| E004 | Invalid field format | Error |
-| E005 | Missing required field | Error |
-| E006 | Invalid timestamp format | Error |
-| E007 | Duplicate record_id | Error |
-| E008 | Unknown field key | Warning |
-| E009 | Invalid value type | Warning |
-| E010 | Invalid version number | Error |
-
----
-
-## 🛠️ Build
-
-```bash
-# Build TypeScript to JavaScript
-npm run build
-
-# Output: dist/
-```
-
----
-
-## 📄 License
-
-MIT
-
----
-
-## 👥 Contributors
-
-- Developer Team (TASK_141 - Parser/Serializer)
-- Developer Team (TASK_142 - CLI Tool)
-
----
-
-**Task IDs**: TASK_141, TASK_142
-**Feature ID**: F-015
-**Version**: 1.0.0
-**Last Updated**: 2026-02-09