Influxdata
/
docs-v2
mirror of https://github.com/influxdata/docs-v2.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
docs-v2/helper-scripts
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
..
cloud-serverless chore(ci): Automation scripts to compare influxdb3 CLI help to reference documentation and generate an audit report, runs influxdb3 core and enterprise using Docker, improves compose.yaml, restructures helper-scripts for different versions 2025-07-07 12:13:36 -05:00
common chore: improve docs-cli with unified flag syntax and YAML config (#6778) 2026-02-04 16:44:35 -06:00
influxdb3-distributed chore(ci): Automation scripts to compare influxdb3 CLI help to reference documentation and generate an audit report, runs influxdb3 core and enterprise using Docker, improves compose.yaml, restructures helper-scripts for different versions 2025-07-07 12:13:36 -05:00
influxdb3-plugins feat(sync): extract style attributes from HTML comments (#6694) 2026-01-06 10:13:18 -06:00
README.md chore: improve docs-cli with unified flag syntax and YAML config (#6778) 2026-02-04 16:44:35 -06:00
build-agent-instructions.js chore(js): formatting 2025-10-08 16:51:25 -05:00

README.md

InfluxData Documentation Helper Scripts

This directory contains scripts to assist with InfluxDB documentation workflows, including release notes generation, CLI/API documentation auditing, and version management.

Directory Structure

helper-scripts/
├── common/                    # Shared scripts used across all products
├── influxdb3-monolith/       # Scripts for InfluxDB 3 Core & Enterprise
├── influxdb3-distributed/    # Scripts for InfluxDB 3 Clustered & Cloud Dedicated
├── cloud-serverless/         # Scripts for InfluxDB Cloud Serverless
└── output/                   # Generated outputs from all scripts

Product Categories

InfluxDB 3 Monolith

  • Products: InfluxDB 3 Core, InfluxDB 3 Enterprise
  • Deployment: Single binary deployment
  • Scripts Location: influxdb3-monolith/

InfluxDB 3 Distributed

  • Products: InfluxDB 3 Clustered, InfluxDB 3 Cloud Dedicated
  • Deployment: Distributed/Kubernetes deployment
  • Scripts Location: influxdb3-distributed/

Cloud Serverless

  • Product: InfluxDB Cloud Serverless
  • Deployment: Fully managed cloud service
  • Scripts Location: cloud-serverless/

Common Scripts

Release Notes Generation

Release notes are generated using the unified docs CLI. See scripts/docs-cli/README.md for full documentation.

Usage:

# Using product keys (resolves paths from config)
npx docs release-notes v3.1.0 v3.2.0 --products influxdb3_core,influxdb3_enterprise

# Using direct repository paths
npx docs release-notes v3.1.0 v3.2.0 --repos ~/repos/influxdb,~/repos/enterprise

common/update-product-version.sh

Updates product version numbers in data/products.yml and related documentation files.

Usage:

./common/update-product-version.sh --product <product> --version <version>

Example:

./common/update-product-version.sh --product core --version 3.2.1

Product-Specific Scripts

InfluxDB 3 Monolith (Core & Enterprise)

See influxdb3-monolith/README.md for detailed documentation.

Key Scripts:

  • audit-cli-documentation.sh - Audits CLI commands against existing documentation
  • setup-auth-tokens.sh - Sets up authentication tokens for local containers

InfluxDB 3 Distributed (Clustered & Cloud Dedicated)

See influxdb3-distributed/README.md for detailed documentation.

Key Scripts:

  • clustered-release-artifacts.sh - Downloads release artifacts for Clustered releases

Output Directory

All scripts write their outputs to organized subdirectories:

output/
├── release-notes/      # Generated release notes
├── cli-audit/         # CLI documentation audit reports
├── api-audit/         # API documentation audit reports
└── artifacts/         # Downloaded release artifacts

GitHub Workflow Integration

These scripts are integrated with GitHub Actions workflows:

  • Workflow: .github/workflows/prepare-release.yml
  • Uses: docs release-notes (unified CLI), update-product-version.sh

Quick Start

  1. Clone the repository

    git clone https://github.com/influxdata/docs-v2.git
cd docs-v2/helper-scripts

  2. Make scripts executable

    find . -name "*.sh" -type f -exec chmod +x {} \;

  3. Run a script

    # Generate release notes (using unified CLI)
npx docs release-notes v3.1.0 v3.2.0 --products influxdb3_core,influxdb3_enterprise

# Audit CLI documentation
npx docs audit main --products influxdb3_core

Contributing

When adding new scripts:

  1. Place in the appropriate product directory
  2. Follow naming conventions (lowercase with hyphens)
  3. Include comprehensive help text and documentation
  4. Update the relevant README files
  5. Test with all applicable products
  6. Ensure outputs go to the output/ directory

Archived Scripts

Deprecated scripts are moved to archive/ subdirectories. These scripts are kept for reference but should not be used in active workflows.