Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/scripts/docs-cli
History
Jason Stirnaman b204de8ffe
chore: improve docs-cli with unified flag syntax and YAML config (#6778) 
* chore(instruction): Add content-editing skill documentation workflow
guide

* Phase 1: Add CLI configuration system

- Add config-loader.js with .env support and smart repo detection
- Add config/.env.example template (no real values)
- Add config/README.md with comprehensive configuration docs
- Configuration uses generic flags (DOCS_ENTERPRISE_ACCESS) not private repo names
- All .env files already gitignored via existing .gitignore pattern

Validation:
✅ Config loads and finds docs-v2 repo automatically
✅ Defaults work without .env file (hasEnterpriseAccess=false)
✅ .env files properly gitignored

* Phase 2: Migrate libraries with security fix and quick wins

**Shared Libraries Added:**
- content-utils.js - Shared content detection and management
- api-auditor.js - API documentation auditing (WITH SECURITY FIX)
- api-audit-reporter.js - API audit report generation
- api-parser.js - Parse API definitions from code
- api-request-parser.js - Parse API request/response specs
- api-doc-scanner.js - Scan documentation for API coverage
- telegraf-auditor.js - Telegraf plugin auditing
- telegraf-audit-reporter.js - Telegraf audit reports
- version-utils.js (NEW) - Version normalization utilities

**SECURITY FIX APPLIED:**
❌ Removed: hardcoded 'https://github.com/influxdata/influxdb_pro.git'
❌ Removed: directory name 'influxdb-pro-clone'
✅ Added: Uses process.env.INFLUXDB_PRO_REPO_URL from config
✅ Added: Clear error message if not configured
✅ Added: Generic directory name 'enterprise-clone'

**Quick Wins Added:**
1. Version normalization (version-utils.js)
   - Handles v3.9, 3.9, v3.9.0, 3.9.0 automatically
   - Suggests matching tags when version not found

2. Enhanced path discovery (config-loader.js)
   - Searches parent directories (up to 3 levels)
   - Finds sibling repositories automatically

3. Progress indicators (deferred to Phase 3)
   - Will add ora package with commands

Validation:
✅ grep shows NO 'influxdb_pro' or 'influxdb-pro' references
✅ api-auditor.js uses process.env.INFLUXDB_PRO_REPO_URL
✅ All library files import successfully

* Phase 3: Add new commands

**Commands Added:**
- audit.js - API and Telegraf documentation auditing
- release-notes.js - Generate release notes from git commits
- add-placeholders.js - Add placeholder syntax to code blocks (moved from scripts/)

**Changes:**
- Created scripts/docs-cli/commands/ directory
- Wrapped add-placeholders.js for CLI router compatibility
- Updated package.json: docs:add-placeholders script path
- Added CLI-MIGRATION-DESIGN.md documentation

**Command Structure:**
All commands export default async function for unified CLI router:
  export default async function commandName({ args, command }) { ... }

Validation:
✅ All three command files present in commands/
✅ add-placeholders.js has export wrapper
✅ package.json points to new location

* Phase 4: Update existing commands (create, edit)

**Commands Updated:**
- Moved docs-create.js → commands/create.js
- Moved docs-edit.js → commands/edit.js

**Changes:**
Both commands now:
- Located in commands/ directory for consistency
- Use unified CLI structure (export default async function)
- Maintain findDocsV2Root() for portability
- Can be called via router or directly

**Files Removed:**
- scripts/docs-cli/docs-create.js (moved to commands/)
- scripts/docs-cli/docs-edit.js (moved to commands/)

Validation:
✅ Old files removed
✅ New files in commands/ directory
✅ Git detected as rename (preserves history)
✅ Both have proper export wrappers for CLI router

* Phase 5: Update router with dynamic command loading

**Router Updated:**
- Replaced basic router with enhanced version from docs-tooling
- Dynamic command loading from ./commands/ directory
- Comprehensive help with all commands listed
- Better error handling with DEBUG mode support
- Version flag (--version) support

**Changes:**
- Updated help text for docs-v2 (was docs-tooling)
- Added add-placeholders command to help
- Fixed configuration path references
- Updated GitHub URL to docs-v2

**Features:**
- Handles --help, --version, unknown commands
- Shows usage on error
- DEBUG env var for stack traces
- Clean error messages for missing commands

Validation:
✅ docs --help shows all 5 commands
✅ Help text references correct paths
✅ Router loads commands dynamically
✅ Error handling works correctly

* Fix: Correct package.json path for --version flag

The router was looking in scripts/package.json instead of repo root.
Updated to go up two levels: docs-cli -> scripts -> repo root

Test: npx docs --version now works correctly

* feat: Enhance docs CLI with placeholders alias and update documentation

- Add command alias support to router (placeholders -> add-placeholders)
- Update docs-cli-workflow SKILL.md with all 5 CLI commands
- Update content-editing SKILL.md quick reference with new commands
- Create consolidated influxdb3-tech-writer agent for all v3 products
- Document tech-writer agent consolidation recommendation

* chore(claude): Consolidate tech-writer agents:

1. **influxdb3-tech-writer** (consolidated) - Handles ALL InfluxDB 3
products
   - InfluxDB 3 Core (self-hosted, open source)
   - InfluxDB 3 Enterprise (self-hosted, licensed)
   - InfluxDB 3 Cloud Dedicated (managed, dedicated)
   - InfluxDB 3 Cloud Serverless (managed, serverless)
   - InfluxDB 3 Clustered (Kubernetes)

2. **influxdb1-tech-writer** (unchanged) - Handles InfluxDB v1 legacy
products
   - InfluxDB v1 OSS
   - InfluxDB v1 Enterprise
   - Chronograf, Kapacitor

* fix: Fix CLI import paths and add npm run scripts

- Fix create.js imports: content-scaffolding, file-operations, url-parser
  now correctly reference ../../lib/ (scripts/lib/)
- Fix edit.js import: url-parser now references ../../lib/
- Fix create.js REPO_ROOT: change const to let for reassignment
- Update package.json with all docs:* npm scripts routing through unified CLI
- Improve error handling: distinguish unknown commands from runtime errors

* fix: Fix remaining dynamic import paths in create.js, add integration tests

- Fix dynamic imports in create.js (lines 487, 1286) using wrong paths
- Add cli-integration.test.js that catches import/module errors by
  actually executing commands, not just testing --help
- Tests verify commands load and run without ERR_MODULE_NOT_FOUND
- Update run-tests.sh to include integration tests

This would have caught the import path errors that broke 'docs create'.

* fix: Fix argument parsing for CLI router, improve integration tests

- create.js: Pass args from router to parseArgs() instead of re-reading
  process.argv (which includes 'create' as first positional)
- add-placeholders.js: Refactor to defer argument parsing to main()
  instead of parsing at module load time
- cli-integration.test.js: Stricter tests that check exit codes and
  error patterns, not just import errors
- Tests now verify commands actually execute successfully, catching
  runtime errors that --help tests would miss

* fix: Fix .tmp directory location and worktree detection

- findDocsV2Root(): Fix package.json name check (@influxdata/docs-site)
- findDocsV2Root(): Prioritize cwd walk-up over env var to find worktrees
- create.js: Change path constants to let for proper reassignment
- .tmp now correctly created in repo root, not scripts/docs-cli/

* chore(docs-cli): Handle piping in create command with helpful errors and
skips

* refactor(docs-cli): unify flag syntax and improve configuration

- Separate --products (product keys) from --repos (paths/URLs) in
  release-notes and audit commands
- Use consistent <positional> --flags syntax across commands
- Replace INFLUXDB_PRO with INFLUXDB_ENTERPRISE naming
- Move config from .env to YAML format (~/.influxdata-docs/docs-cli.yml)
- Output release notes to .tmp/release-notes/ (gitignored)
- Add integration tests for new flag syntax
- Update help text to reflect unified CLI usage

* chore: remove deprecated release-notes script and configs

- Remove helper-scripts/common/generate-release-notes.js (migrated to unified CLI)
- Remove orphaned config files (influxdb-v1.json, influxdb-v2.json, etc.)
- Update workflows to reference unified CLI (docs release-notes)
- Update helper-scripts READMEs to remove deprecated documentation

* feat(docs-cli): add path support to --products flag

Add a unified product-resolver module that accepts content paths
(e.g., /influxdb3/core) in addition to product keys (influxdb3_core)
for the --products flag across all docs CLI commands.

Changes:
- Add lib/product-resolver.js for path-to-key resolution
- Update audit command: remove positional args, use --products/--repos
- Update release-notes: add path support, enforce mutual exclusion
- Update create: add path support via resolveProducts()
- Update main CLI help text with new syntax examples
- Add 30 unit tests for product-resolver module
- Update integration tests for new audit syntax

BREAKING CHANGE: audit command no longer accepts positional arguments.
Use `docs audit --products influxdb3_core` instead of `docs audit core`.

* Update skills and commands for new docs CLI syntax

- Update content-editing skill with new --products flag syntax
  - Document path-to-key resolution (e.g., /influxdb3/core -> influxdb3_core)
  - Update Quick Reference table with correct command examples

- Update docs-cli-workflow skill
  - Add examples showing both product keys and content paths
  - Document mutual exclusion between --products and --repos
  - Update audit command syntax (removed positional arguments)

- Replace enhance-release-notes.md with prepare-release-notes.md
  - New command documents docs release-notes CLI usage
  - Includes examples with --products and --repos flags

* feat(github): add Copilot instructions management and DRY refactor

- Add copilot-instructions-agent.md for creating/managing Copilot instructions
- DRY refactor of copilot-instructions.md (485→240 lines, 50% reduction)
- Update all pattern-specific instructions to reference Claude skills
- Add comprehensive cross-references between Copilot and Claude resources
- Document unified docs CLI with non-blocking defaults
- Add COPILOT-INSTRUCTIONS-UPDATE.md summary document

Key improvements:
- Single source of truth (Claude skills) with focused Copilot summaries
- Concise, scannable instructions with links to detailed resources
- Consistent structure across all instruction files
- Better guidance on when to use CLI tools vs direct editing

* refactor(docs-cli): fix unused code and env var naming

Address PR feedback from Copilot code review:

- Rename INFLUXDB_ENTERPRISE_REPO_URL to INFLUXDB3_ENTERPRISE_REPO_URL
  for consistency with InfluxDB 3 naming conventions
- Fix misleading error message to point to correct config location
- Remove unused detectEnterpriseEndpoints import from api-auditor.js
- Remove unused endpointParams variable from api-auditor.js
- Remove unused auditType variable in audit.js loop
- Remove unused assertDeepEquals function from product-resolver tests
 		2026-02-04 16:44:35 -06:00
..
__tests__ chore: improve docs-cli with unified flag syntax and YAML config (#6778) 2026-02-04 16:44:35 -06:00
commands chore: improve docs-cli with unified flag syntax and YAML config (#6778) 2026-02-04 16:44:35 -06:00
config chore: improve docs-cli with unified flag syntax and YAML config (#6778) 2026-02-04 16:44:35 -06:00
lib chore: improve docs-cli with unified flag syntax and YAML config (#6778) 2026-02-04 16:44:35 -06:00
README.md fix(cli): Make docs edit non-blocking and reorganize CLI code (#6721) 2026-01-13 21:47:09 -06:00
docs-cli.js chore: improve docs-cli with unified flag syntax and YAML config (#6778) 2026-02-04 16:44:35 -06:00

README.md

Documentation CLI Tools

This directory contains command-line tools for working with the InfluxData documentation repository.

Structure

scripts/docs-cli/
├── README.md                    # This file
├── docs-cli.js                  # Main CLI entry point
├── docs-edit.js                 # Edit existing documentation
├── docs-create.js               # Create new documentation
├── lib/                         # CLI-specific modules
│   ├── editor-resolver.js       # Smart editor selection
│   ├── process-manager.js       # Process spawning (detached/attached)
│   └── url-parser.js            # URL parsing utilities
└── __tests__/                   # Unit tests
    ├── editor-resolver.test.js  # Editor resolution tests
    ├── process-manager.test.js  # Process management tests
    └── run-tests.sh             # Test runner script

Installation

The docs command is automatically configured when you run:

yarn install

This creates a symlink in node_modules/.bin/docs pointing to docs-cli.js.

Commands

docs edit - Edit Existing Documentation

Opens documentation files in your preferred editor. Non-blocking by default (agent-friendly).

Usage

# Quick edit (exits immediately, editor in background)
docs edit <url-or-path>
docs edit https://docs.influxdata.com/influxdb3/core/admin/
docs edit /influxdb3/core/admin/

# Interactive edit (waits for editor to close)
docs edit <url-or-path> --wait

# List files without opening
docs edit <url-or-path> --list

# Use specific editor
docs edit <url-or-path> --editor nano

Options

  • --list - List files without opening editor
  • --wait - Wait for editor to close (blocking mode)
  • --editor <command> - Use specific editor (e.g., vim, nano, code --wait)

Editor Configuration

The CLI selects an editor in this priority order:

  1. --editor flag
  2. DOCS_EDITOR environment variable
  3. VISUAL environment variable
  4. EDITOR environment variable
  5. System default (vim, nano, etc.)

Examples:

# Set editor for all commands
export EDITOR=vim

# Set editor specifically for docs CLI
export DOCS_EDITOR=nano

# Use VS Code with built-in wait flag
export DOCS_EDITOR="code --wait"

docs create - Create New Documentation

Scaffolds new documentation pages with proper frontmatter and structure.

Usage

# Create from draft file
docs create <draft-path> --products <product-key>

# Create at specific URL location
docs create --url <url> --from-draft <draft-path>

# Create and open files in editor (non-blocking)
docs create <draft-path> --products <product-key> --open

# Create and open files, wait for editor (blocking)
docs create <draft-path> --products <product-key> --open --wait

# Use specific editor
docs create <draft-path> --products <product-key> --open --editor nano

Options

  • --open - Open created files in editor after creation (non-blocking by default)
  • --wait - Wait for editor to close (use with --open)
  • --editor <command> - Use specific editor (e.g., vim, nano, code --wait)
  • --products <keys> - Comma-separated product keys
  • --url <url> - Documentation URL for new content location
  • --dry-run - Show what would be created without creating files
  • --yes - Skip confirmation prompt

See docs create --help for full options.

Editor Configuration

The --open flag uses the same editor resolution as docs edit:

  1. --editor flag
  2. DOCS_EDITOR environment variable
  3. VISUAL environment variable
  4. EDITOR environment variable
  5. System default (vim, nano, etc.)

Examples:

# Set editor for docs CLI
export DOCS_EDITOR=nano

# Create and open in one command
docs create drafts/feature.md --products influxdb3_core --open

# Create, open, and wait
docs create drafts/feature.md --products influxdb3_core --open --wait

docs placeholders - Add Placeholder Syntax

Adds placeholder syntax to code blocks for interactive examples.

docs placeholders <file-path>

Testing

Run All Tests

bash scripts/docs-cli/__tests__/run-tests.sh

Run Individual Tests

node scripts/docs-cli/__tests__/editor-resolver.test.js
node scripts/docs-cli/__tests__/process-manager.test.js

Manual Verification

# Test non-blocking mode (should exit immediately)
time docs edit /influxdb3/core/admin/ --editor echo

# Test blocking mode (should wait)
time docs edit /influxdb3/core/admin/ --wait --editor echo

# Test list mode
docs edit /influxdb3/core/admin/ --list

Implementation Details

Non-Blocking by Default

The docs edit command spawns the editor as a detached process and exits immediately. This prevents AI agents and automation scripts from hanging indefinitely.

Key modules:

  • lib/editor-resolver.js - Resolves the editor command from multiple sources
  • lib/process-manager.js - Spawns processes in detached (non-blocking) or attached (blocking) mode

URL Parsing

The CLI supports both full URLs and path-only formats:

# Both of these work:
docs edit https://docs.influxdata.com/influxdb3/core/admin/
docs edit /influxdb3/core/admin/

The lib/url-parser.js module handles URL parsing and maps documentation URLs to source files in the repository.

Shared Content Detection

When a page uses shared content (via the source frontmatter field), the CLI identifies both:

  1. The frontmatter file (defines page metadata)
  2. The shared source file (contains actual content)

Both files are opened for editing.

Issue #21 Fix

This directory structure was created as part of fixing issue #21, where the docs edit command caused agents to hang waiting for the editor.

Changes:

  • Made non-blocking the default behavior
  • Added --wait flag for interactive editing
  • Added --editor flag for explicit editor selection
  • Improved editor resolution with multiple fallbacks
  • Organized CLI code into dedicated directory

Documentation:

Contributing

When modifying these tools:

  1. Update tests in __tests__/
  2. Run the test suite: bash scripts/docs-cli/__tests__/run-tests.sh
  3. Update this README if adding new commands or features
  4. Test both blocking and non-blocking modes
  5. Verify editor resolution works correctly

Help

For command-specific help:

docs --help
docs edit --help
docs create --help

For general documentation contribution guidelines, see DOCS-CONTRIBUTING.md.