docopslab-dev 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9a31711e06193c9ba747b543752fffc6db59d0a9f97fc78bf696e091f96e1306
-  data.tar.gz: 94139a83f22c0f878c76244aa9c0d413325efa1ddad8878ea730d74502f9d832
+  metadata.gz: c8417e50ad63a4c8d98af45af088b4088b7fb75106d2997da327c51d2d106f5d
+  data.tar.gz: 0be1d194d518f593d9523b7bd446113a9a140f5861bf538bc38791076a3616cf
 SHA512:
-  metadata.gz: 80744416b127b753a0b8c8eb6b9ad9c8b4e4a1b6f8a60e4299d5a13ab66d95ce9b79168c9fd57b7da08e56c7d9d75c6e412e56fb4bdc171df1b9e6fc51688ff4
-  data.tar.gz: f3f858dd1fa05e9d2ee3303bb682a748c02d83c537fa5649a883269e55a4fe671464ba0cece63ec71aa6a635ff5e2ed9ba5867ffe661e3c6000d9e162a092abc
+  metadata.gz: 139611f20da4c0fbe7a68b497c930989e4fbb7019633d627e3039248862a25c8381a4257b3be88edbeebaba29578af9e3e642a261250c5d179c632982f58b204
+  data.tar.gz: 786b54d7f24f35f80d0483ad5692b54ce737e7cc92d788ff2f959452789e8706c54a11b55979a0866ab64c35be1fbd78acc7b37065341eab2184f85cc4969fc1

data/README.adoc

@@ -51,7 +51,7 @@ Internal development tooling for working on DocOps Lab codebases.
 [IMPORTANT]
 ====
 The environment described and provided here is _not_ optimized for DocOps Lab _applications_ used in third-party projects.
-For your own applications of DocOps Labs products like ReleaseHx and Issuer, see link:{docopslab_lab_www_url}/projects/docops-box[DocOps Box] for a full-featured docs-focused workspace, runtime, and production environment.
+For your own applications of DocOps Labs products like ReleaseHx and Issuer, see link:{docopslab_lab_www_url}/projects/box[DocOps Box] for a full-featured docs-focused workspace, runtime, and production environment.
 ====
 // end::docopsbox[]
 
@@ -202,6 +202,8 @@ Assuming you are not initializing a new project, you can skip to <<environment-s
 
 If you are introducing `docopslab-dev` to an existing project, you first need to integrate and initialize it.
 
+If you are introducing `docopslab-dev` to an existing project, integrate it into your existing Rakefile:
+
 . Add `docopslab-dev` to the project's `Gemfile`.
 +
 [source,ruby]
@@ -255,17 +257,28 @@ Every project using `docopslab-dev` is configured through a single manifest file
 
 The manifest has four top-level keys, each documented in detail in the relevant section:
 
+ifdef::env-github[:usage_link_managed_tools: <<managed-tools,managed tools>>]
+ifdef::env-github[:usage_link_file_syncing: <<file-syncing,file syncing>>]
+ifdef::env-github[:usage_link_technical_documentation: <<technical-documentation,technical documentation>>]
+ifdef::env-github[:usage_link_sync_cast: <<sync-cast,SyncCast>>]
+ifdef::env-github[:usage_link_remote_library: <<remote-library,Remote Asset Library>>]
+ifndef::env-github[:usage_link_managed_tools: link:/docs/lab-dev-usage/#managed-tools[managed tools]]
+ifndef::env-github[:usage_link_file_syncing: link:/docs/lab-dev-usage/#file-syncing[file syncing]]
+ifndef::env-github[:usage_link_technical_documentation: link:/docs/lab-dev-usage/#technical-documentation[technical documentation]]
+ifndef::env-github[:usage_link_sync_cast: link:/docs/lab-dev-usage/#sync-cast[SyncCast]]
+ifndef::env-github[:usage_link_remote_library: link:/docs/lab-dev-usage/#remote-library[Remote Asset Library]]
+
 `tools:`::
-<<managed-tools>>: active linters and their config file mappings.
+{usage_link_managed_tools}: active linters and their config file mappings.
 
 `docs:`::
-<<file-syncing>> > <<technical-documentation>>: agent docs and guides to sync.
+{usage_link_file_syncing} > {usage_link_technical_documentation}: agent docs and guides to sync.
 
 `templates:`::
-<<sync-cast>>: Liquid-rendered source-to-target entries.
+{usage_link_sync_cast}: Liquid-rendered source-to-target entries.
 
 `library:`::
-<<remote-library,Remote Asset Library>>: library source and cache settings.
+{usage_link_remote_library}: library source and cache settings.
 // end::manifest-intro[]
 
 // end::setup[]
@@ -335,8 +348,23 @@ All tools use the host project's Gemfile for version consistency.
 Make sure container-managed paths are not tracked in Git.
 Add `.config/.vendor/`, `scripts/.vendor`, and `.bundle/` to `.gitignore`.
 ====
+
+[[docker-caching]]
+==== Advanced library caching with Docker
+
+Mount your system cache directory to the container for persistent caching of library assets across sessions and projects.
+
+....
+docker run -it --rm \
+  -v "$(pwd):/workspace" \
+  -v ~/.cache/docopslab:/home/docops/.cache/docopslab \
+  docopslab/dev
+....
+
 // end::usage[]
 
+// tag::reference[]
+
 See <<more-example-commands>> for additional common commands.
 
 [[handy-labdev-tasks]]
@@ -480,6 +508,7 @@ For all other projects, the gem works in a standard package consumption mode:
 [TIP]
 The `labdev:sync:vale` task updates both the base config and the style packages.
 
+ifdef::site-gen-jekyll[]
 A project's `.config/vale.local.ini` should look something like the one for this repository (DocOps/lab).
 
 .A snippet from DocOps/lab's `.config/vale.local.ini`
@@ -487,6 +516,7 @@ A project's `.config/vale.local.ini` should look something like the one for this
 ----
 include::../../.config/vale.local.ini[tag="core-settings"]
 ----
+endif::[]
 
 This dual-mode system provides a robust workflow for both developing and consuming the centralized Vale styles.
 
@@ -906,6 +936,7 @@ library:
 The fetch tasks require either the `gh` CLI or `git` to be available on your `PATH`.
 The `gh` CLI is preferred and will be used when present.
 
+// end::reference[]
 
 // tag::workflow[]
 [[task-reference]]
@@ -992,6 +1023,7 @@ Vale::
 HTMLProofer::
 +
  bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site
+
 // end::standard-usage[]
 // end::usage[]
 // end::workflow[]
@@ -1005,8 +1037,8 @@ Override settings by editing the project configs:
 
 * `{default_manifest_path}`
 * `.config/rubocop.yml`
-* `.config/vale.ini`
-* `.config/htmlproofer.yml`
+* `.config/vale.local.ini`
+* `.config/htmlproofer.local.yml`
 * `.config/actionlint.yml`
 * `.config/shellcheckrc`
 
@@ -1017,15 +1049,14 @@ Your configurations will inherit from the base configurations and source librari
 
 Projects using `docopslab-dev` will have a configuration structure like the following:
 
-[source,tree]
-----
+....
 .config/
 ├── docopslab-dev.yml             # Project manifest (tracked)
 ├── actionlint.yml                # Project config (tracked; inherits from base)
 ├── htmlproofer.local.yml         # Project config (tracked; inherits from base)
 ├── htmlproofer.yml               # Generated config (untracked)
 ├── rubocop.yml                   # Project config (tracked; inherits from base)
-├── shellcheckrc                 # ShellCheck config (tracked)
+├── shellcheckrc                  # ShellCheck config (tracked)
 ├── vale.ini                      # Generated active config (untracked)
 ├── vale.local.ini                # Project config (tracked; inherits from base)
 ├── .vendor/                      # Base configs (untracked; synced)
@@ -1038,7 +1069,7 @@ scripts/                          # Project override scripts
 .github/workflows/                # CI/CD workflows (tracked)
 env.docopslab                     # Environment variables (git tracked)
 env.private                       # Environment variables (git ignored)
-----
+....
 // end::customization[]
 
 

data/docopslab-dev.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
   spec.metadata['changelog_uri'] = 'https://github.com/DocOps/lab/blob/main/gems/docopslab-dev/README.adoc'
   spec.metadata['rubygems_mfa_required'] = 'true'
 
-  spec.files = Dir.glob('{lib,docs}/**/*') +
+  spec.files = Dir.glob('lib/**/*') +
                %w[README.adoc LICENSE docopslab-dev.gemspec] +
                Dir.glob('specs/data/*')
 
@@ -47,7 +47,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'bundler-audit',  '~> 0.9'
 
   # Testing and coverage
-  spec.add_dependency 'html-proofer',   '~> 5.0'
+  spec.add_dependency 'html-proofer',   '~> 5.2'
   spec.add_dependency 'inch',           '~> 0.8'
   spec.add_dependency 'simplecov',      '~> 0.22'
 

data/lib/docopslab/dev/docker_aware.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module DocOpsLab
+  module Dev
+    # Detects and provides utilities for Docker container environments.
+    module DockerAware
+      class << self
+        # True if running inside a Docker container.
+        # Checks:
+        #   1. DOCOPSLAB_IN_DOCKER environment variable (set in Dockerfile)
+        #   2. /.dockerenv marker file (standard Docker indicator)
+        def running_in_docker?
+          ENV['DOCOPSLAB_IN_DOCKER'] == 'true' || File.exist?('/.dockerenv')
+        end
+
+        # True if Docker but without access to host's cache directory.
+        # This is the case when user runs: docker run -v "$(pwd):/workspace" ...
+        # without explicitly mounting ~/.cache/docopslab
+        def docker_without_cache?
+          running_in_docker? && !cache_mount_accessible?
+        end
+
+        # True if the Docker container can access the host's cache mount.
+        # Checks if /home/docops/.cache/docopslab exists and is readable.
+        def cache_mount_accessible?
+          cache_path = File.expand_path('~/.cache/docopslab')
+          File.exist?(cache_path) && File.directory?(cache_path) && File.readable?(cache_path)
+        rescue StandardError
+          false
+        end
+
+        # Workspace-relative cache path for Docker-only users.
+        # Returns path like /workspace/.docopslab-cache/
+        def workspace_cache_path
+          File.join('/workspace', '.docopslab-cache')
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/initializer.rb

@@ -71,8 +71,8 @@ module DocOpsLab
           true
         end
 
-        def bootstrap_project
-          puts '� Bootstrapping DocOps Lab project...'
+        def bootstrap_project context = nil
+          puts '🚀 Bootstrapping DocOps Lab project...'
           puts ''
 
           created = []
@@ -90,13 +90,27 @@ module DocOpsLab
           puts ''
           if created.any?
             puts "✅ Bootstrap complete! Created: #{created.join(', ')}"
-            puts ''
-            puts 'Next steps:'
-            puts '  1. bundle exec rake labdev:sync:all  # or: docker run ... labdev:sync:all'
-            puts '  2. Start using labdev tasks!'
           else
-            puts '✅ Project already initialized, nothing to create'
+            puts '✅ Bootstrap files already exist'
           end
+
+          # Initialize templates from manifest (if context provided, use it; else use Dev context)
+          context ||= Dev
+          puts ''
+          puts '🎨 Initializing templates from manifest...'
+          template_results = CastOps.init_cast_targets(context)
+
+          if template_results.any?
+            puts "✅ Initialized #{template_results.size} template(s)"
+          else
+            puts '✅ Templates already initialized'
+          end
+
+          puts ''
+          puts 'Next steps:'
+          puts '  1. bundle exec rake labdev:sync:all  # or: docker run ... labdev:sync:all'
+          puts '  2. Review and customize the generated files'
+          puts '  3. Start using labdev tasks: bundle exec rake labdev:check:env'
         end
       end
     end

data/lib/docopslab/dev/library.rb

@@ -11,7 +11,16 @@ require_relative 'library/fetch'
 module DocOpsLab
   module Dev
     # Remote library fetch, cache, and resolution.
-    # Manages a host-wide asset cache at ~/.cache/docopslab/dev/library/.
+    # Manages a host-wide asset cache at ~/.cache/docopslab/dev/library/ (native)
+    # or ./.docopslab-cache/ (Docker without cache mount).
+    #
+    # Docker Cache Strategy:
+    # - If running in Docker with host cache mounted (-v ~/.cache/docopslab:...):
+    #   uses host cache path (DockerAware.cache_mount_accessible? = true)
+    # - If running in Docker without cache mount: uses workspace-relative cache
+    #   (./.docopslab-cache/) which persists with the project
+    # - If running natively: uses ~/.cache/docopslab/ via XDG_CACHE_HOME
+    #
     # Callers should use this module directly: Library.fetch!, Library.resolve(path), etc.
     module Library
       class << self
@@ -285,6 +294,10 @@ module DocOpsLab
           # local_path points to the 'current' snapshot dir, so its parent is
           # the cache root (mirrors Cache::XDG_CACHE_SUBPATH layout).
           cr = File.join(File.expand_path(config['local_path']), '..') if cr.nil? && local_path_active?(config)
+
+          # In Docker without access to host cache, use workspace-local cache
+          cr = DockerAware.workspace_cache_path if cr.nil? && DockerAware.docker_without_cache?
+
           Cache.with_root_override(cr ? File.expand_path(cr) : nil, &)
         end
 

data/lib/docopslab/dev/linters.rb

@@ -488,10 +488,17 @@ module DocOpsLab
         def check_shebang file_path
           return false unless File.exist?(file_path)
 
-          first_line = File.open(file_path, &:readline).strip
+          lines = File.readlines(file_path).map(&:strip)
+          return false if lines.empty?
+
+          first_line = lines[0]
+          second_line = lines[1]
+
+          # If second line has shellcheck directive for sh, require sh shebang
+          return first_line == '#!/bin/sh' if second_line == '# shellcheck shell=sh'
+
+          # Otherwise, require bash shebang
           first_line == '#!/usr/bin/env bash'
-        rescue EOFError
-          false
         rescue StandardError => e
           puts "⚠️  Error checking shebang for #{file_path}: #{e.message}"
           false

data/lib/docopslab/dev/version.rb

@@ -2,7 +2,7 @@
 
 module DocOpsLab
   module Dev
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
     RUBY_TARGET = '3.2.7'
   end
 end

data/lib/docopslab/dev.rb

@@ -8,6 +8,7 @@ require 'pathname'
 require 'shellwords'
 require_relative 'dev/version' # includes RUBY_TARGET
 require_relative 'dev/paths'
+require_relative 'dev/docker_aware'
 require_relative 'dev/manifest'
 require_relative 'dev/spell_check'
 require_relative 'dev/log_parser'
@@ -195,7 +196,7 @@ module DocOpsLab
       end
 
       def bootstrap_project
-        Initializer.bootstrap_project
+        Initializer.bootstrap_project(self)
       end
 
       def install_vale_styles

data/specs/data/default-manifest.yml

@@ -39,6 +39,14 @@ tools:
       - source: vale/project.ini
         target: .config/vale.local.ini
         synced: false
+    paths:
+      lint: ['.']
+      skip:
+        - build/*
+        - specs/*
+        - .agent/**/*
+        - .config/.vendor/**/*
+      exts: ['adoc']
 
   - tool: htmlproofer
     enabled: false  # Disabled by default, enable per project

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docopslab-dev
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - DocOps Lab
@@ -211,14 +211,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: inch
   requirement: !ruby/object:Gem::Requirement
@@ -258,47 +258,13 @@ files:
 - LICENSE
 - README.adoc
 - docopslab-dev.gemspec
-- docs/agent/index.md
-- docs/agent/misc/bash-styles.md
-- docs/agent/missions/conduct-release.md
-- docs/agent/missions/setup-new-project.md
-- docs/agent/roles/devops-release-engineer.md
-- docs/agent/roles/docops-engineer.md
-- docs/agent/roles/planner-architect.md
-- docs/agent/roles/product-engineer.md
-- docs/agent/roles/product-manager.md
-- docs/agent/roles/project-manager.md
-- docs/agent/roles/qa-testing-engineer.md
-- docs/agent/roles/tech-docs-manager.md
-- docs/agent/roles/tech-writer.md
-- docs/agent/skills/asciidoc.md
-- docs/agent/skills/bash-cli-dev.md
-- docs/agent/skills/code-commenting.md
-- docs/agent/skills/fix-broken-links.md
-- docs/agent/skills/fix-jekyll-asciidoc-build-errors.md
-- docs/agent/skills/fix-spelling-issues.md
-- docs/agent/skills/git.md
-- docs/agent/skills/github-issues.md
-- docs/agent/skills/product-release-rollback-and-patching.md
-- docs/agent/skills/rake-cli-dev.md
-- docs/agent/skills/readme-driven-dev.md
-- docs/agent/skills/release-history.md
-- docs/agent/skills/ruby.md
-- docs/agent/skills/schemagraphy-sgyml.md
-- docs/agent/skills/tests-running.md
-- docs/agent/skills/tests-writing.md
-- docs/agent/skills/write-the-docs.md
-- docs/agent/topics/common-project-paths.md
-- docs/agent/topics/dev-tooling-usage.md
-- docs/agent/topics/devops-ci-cd.md
-- docs/agent/topics/product-docs-deployment.md
-- docs/library-readme.adoc
 - lib/docopslab/dev.rb
 - lib/docopslab/dev/auto_fix_asciidoc.rb
 - lib/docopslab/dev/cast_ops.rb
 - lib/docopslab/dev/checkers.rb
 - lib/docopslab/dev/config_manager.rb
 - lib/docopslab/dev/data_utils.rb
+- lib/docopslab/dev/docker_aware.rb
 - lib/docopslab/dev/file_utils.rb
 - lib/docopslab/dev/git_branch.rb
 - lib/docopslab/dev/git_hooks.rb

data/docs/agent/index.md

@@ -1,76 +0,0 @@
-# DocOps Lab AI Agent Documentation
-
-## Roles
-
-#### [AGENT ROLE: Assistant Planner / Project Architect](/docs/agent/planner-architect/)
-
-#### [AGENT ROLE: Assistant Product Manager](/docs/agent/product-manager/)
-
-#### [AGENT ROLE: DevOps / Release Engineer](/docs/agent/devops-release-engineer/)
-
-#### [AGENT ROLE: DocOps Engineer](/docs/agent/docops-engineer/)
-
-#### [AGENT ROLE: Product Engineer](/docs/agent/product-engineer/)
-
-#### [AGENT ROLE: Project Manager](/docs/agent/project-manager/)
-
-#### [AGENT ROLE: QA / Testing Specialist](/docs/agent/qa-testing-engineer/)
-
-#### [AGENT ROLE: Technical Documentation Manager](/docs/agent/tech-docs-manager/)
-
-#### [AGENT ROLE: Technical Writer](/docs/agent/tech-writer/)
-
-## Skills
-
-#### [AI Agent Instructions for Git Operations](/docs/agent/git/)
-
-#### [AI Agent’s Guide to Writing in AsciiDoc](/docs/agent/asciidoc/)
-
-#### [Agent Rake CLI Guide](/docs/agent/rake-cli-dev/)
-
-#### [Bash CLI Development for Agents](/docs/agent/bash-cli-dev/)
-
-#### [Bash Coding for Agents](/docs/agent/bash-styles/)
-
-#### [Code Commenting](/docs/agent/code-commenting/)
-
-#### [Documenting Product Changes](/docs/agent/write-the-docs/)
-
-#### [Fix Broken Links](/docs/agent/fix-broken-links/)
-
-#### [Fix Jekyll AsciiDoc Build Errors](/docs/agent/fix-jekyll-asciidoc-build-errors/)
-
-#### [Fix Spelling Issues in Documentation](/docs/agent/fix-spelling-issues/)
-
-#### [GitHub Issues Management for AI Agents](/docs/agent/github-issues/)
-
-#### [Preparing a Version Release History Document](/docs/agent/release-history/)
-
-#### [README-driven Development](/docs/agent/readme-driven-dev/)
-
-#### [Rolling Back and/or Patching a Product Release](/docs/agent/product-release-rollback-and-patching/)
-
-#### [Ruby Coding Guide for DocOps Lab AI Agents](/docs/agent/ruby/)
-
-#### [Running Tests in DocOps Lab Projects](/docs/agent/tests-running/)
-
-#### [SchemaGraphy/SGYML 101](/docs/agent/schemagraphy-sgyml/)
-
-#### [Writing Tests for DocOps Lab Projects](/docs/agent/tests-writing/)
-
-## Topics
-
-#### [AI Agent Instructions for In-house Dev-Tooling Usage](/docs/agent/dev-tooling-usage/)
-
-#### [AI Agent Orientation to DocOps Lab DevOps/CI/CD Practices](/docs/agent/devops-ci-cd/)
-
-#### [Overview of Common Paths/Files in DocOps Lab Projects](/docs/agent/common-project-paths/)
-
-#### [Product Documentation Deployment](/docs/agent/product-docs-deployment/)
-
-## Missions
-
-#### [MISSION: Conduct a Product Release](/docs/agent/conduct-release/)
-
-#### [MISSION: Start a New DocOps Lab Project](/docs/agent/setup-new-project/)
-