Queue

Article Queue

Manage the article queue stored in the SQLite database (.article_writer/article_writer.db).

Data Access

All data is stored in the articles table of the SQLite database. Use the provided scripts for all operations:

# Queue summary
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/queue.ts status

# List articles (with filters)
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/queue.ts list [filter]

# Show article details
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/queue.ts show <id>

# Stats and operations
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/article-stats.ts --summary
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/article-stats.ts --get <id>
bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/article-stats.ts --set-status <status> <id>

Schema Reference

See references/schema-reference.md for fields.

Key Fields

Author Reference

Articles reference authors via author_id, author_name, and author_languages columns:

{
  "author_id": "mwguerra",
  "author_name": "MW Guerra",
  "author_languages": ["pt_BR", "en_US"]
}

If author not specified, the default author (lowest sort_order) is used.

Output Files (per language)

{
  "output_folder": "content/articles/2025_01_15_rate-limiting/",
  "output_files": [
    {
      "language": "pt_BR",
      "path": "content/articles/2025_01_15_rate-limiting/rate-limiting.pt_BR.md",
      "translated_at": "2025-01-15T14:00:00Z"
    },
    {
      "language": "en_US",
      "path": "content/articles/2025_01_15_rate-limiting/rate-limiting.en_US.md",
      "translated_at": "2025-01-15T16:00:00Z"
    }
  ]
}

Timestamps

• created_at: When task was added to queue
• written_at: When primary article was completed
• published_at: When article went live
• updated_at: Last modification

Operations

Status Summary

bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/queue.ts status

Filter by Author

bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/queue.ts list author:mwguerra

Filter by Language

bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/queue.ts list lang:en_US

Update After Writing

bun run "${CLAUDE_PLUGIN_ROOT}"/scripts/queue.ts update <id> status:draft

Add Translation

Update the output_files JSON column with additional language entries.

Status Flow

pending -> in_progress -> draft -> review -> published
               |
           archived

Default Author

When adding tasks without author: 1. Query default author: SELECT * FROM authors ORDER BY sort_order ASC LIMIT 1 2. Store author_id, author_name, author_languages in article record

Validation

Before processing:

• Verify author_id exists in authors table
• Validate languages are subset of author's languages
• Check all required fields present

Schema Reference

Storage: All data is stored in a SQLite database at .article_writer/article_writer.db using Bun's built-in bun:sqlite. The database uses WAL mode for concurrent reads and foreign keys for referential integrity.

Article Task Fields

Author Reference

Articles store author references as separate columns:

author_id TEXT REFERENCES authors(id),
author_name TEXT,
author_languages TEXT  -- JSON array

Output File

Stored in the output_files JSON column as an array:

[
  {
    "language": "pt_BR",
    "path": "content/articles/2025_01_15_slug/slug.pt_BR.md",
    "translated_at": "2025-01-15T14:00:00Z"
  }
]

Source Reference

Stored in the sources_used JSON column as an array.

[
  {
    "url": "https://laravel.com/docs/11.x/rate-limiting",
    "title": "Rate Limiting - Laravel Documentation",
    "summary": "Official docs covering RateLimiter facade and configuration",
    "usage": "Primary reference for syntax and best practices",
    "accessed_at": "2025-01-15T10:00:00Z",
    "type": "documentation"
  }
]

Companion Project Info

Stored in the companion_project JSON column.

Companion projects must be COMPLETE and RUNNABLE.

{
  "type": "code",
  "path": "code/",
  "description": "Complete Laravel app demonstrating rate limiting",
  "technologies": ["Laravel 12", "Pest 4", "SQLite"],
  "scaffold_command": "composer create-project laravel/laravel code",
  "has_tests": true,
  "files": [
    "app/Http/Middleware/RateLimitMiddleware.php",
    "tests/Feature/RateLimitTest.php"
  ],
  "run_command": "php artisan serve",
  "run_instructions": "composer install && php artisan serve",
  "test_command": "php artisan test",
  "verified": true,
  "verified_at": "2025-01-15T14:00:00Z"
}

Settings (settings table)

Global settings stored as a singleton row (id=1) in the settings table.

Structure

Two JSON columns:

Companion Project Defaults Fields

Default Values (code type)

{
  "code": {
    "technologies": ["Laravel 12", "Pest 4", "SQLite"],
    "has_tests": true,
    "path": "code/",
    "run_instructions": "composer install && cp .env.example .env && php artisan key:generate && touch database/database.sqlite && php artisan migrate --seed && php artisan test",
    "test_command": "php artisan test"
  }
}

Merging with Article Companion Projects

Article-specific values override defaults:

settings defaults        article companion_project    result
─────────────            ────────────────────────     ──────
technologies: [L12]      technologies: [L11]    ->   [L11]
has_tests: true          (not set)              ->   true
path: "code/"            path: "example/"       ->   "example/"

Database Tables

Enums

area

Architecture, Backend, Business, Database, DevOps, Files, Frontend, Full-stack, JavaScript, Laravel, Native Apps, Notifications, Performance, PHP, Quality, Security, Soft Skills, Testing, Tools, AI/ML

difficulty

Beginner, Intermediate, Advanced, All Levels

content_type

Tutorial, Deep-dive, Guide, Comparison, Quick Tip, Case Study, Opinion, etc.

estimated_effort

Short, Medium, Long, Long (Series)

status

pending, in_progress, draft, review, published, archived

Timestamps

Example Task

{
  "id": 1,
  "title": "Implementing Rate Limiting in Laravel 11",
  "subject": "Rate Limiting",
  "area": "Laravel",
  "tags": "laravel, rate-limiting, api",
  "difficulty": "Intermediate",
  "relevance": "High",
  "content_type": "Tutorial with Examples",
  "estimated_effort": "Medium",
  "versions": "Laravel 11.x",
  "series_potential": "Yes",
  "prerequisites": "Basic Laravel",
  "reference_urls": "https://laravel.com/docs",
  "author_id": "mwguerra",
  "author_name": "MW Guerra",
  "author_languages": ["pt_BR", "en_US"],
  "status": "draft",
  "output_folder": "content/articles/2025_01_15_rate-limiting/",
  "output_files": [
    {
      "language": "pt_BR",
      "path": "content/articles/2025_01_15_rate-limiting/rate-limiting.pt_BR.md",
      "translated_at": "2025-01-15T14:00:00Z"
    }
  ],
  "sources_used": [
    {
      "url": "https://laravel.com/docs/11.x/rate-limiting",
      "title": "Rate Limiting - Laravel Documentation",
      "summary": "Official docs on RateLimiter facade and middleware",
      "usage": "Primary reference for all code examples",
      "accessed_at": "2025-01-15T10:00:00Z",
      "type": "documentation"
    }
  ],
  "companion_project": {
    "type": "code",
    "path": "code/",
    "description": "Minimal Laravel app demonstrating rate limiting",
    "technologies": ["Laravel 11", "SQLite", "Pest 3"],
    "has_tests": true,
    "files": [
      "app/Providers/AppServiceProvider.php",
      "routes/api.php",
      "tests/Feature/RateLimitTest.php"
    ],
    "run_instructions": "composer install && php artisan test"
  },
  "created_at": "2025-01-10T10:00:00Z",
  "written_at": "2025-01-15T14:00:00Z"
}