pagecord-cli 0.3.0 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e6a9d37234707507835ff1e87b324bccfacc7d680515b9674f0f0fa454cd704
-  data.tar.gz: d0628c7e0c4e1273cb24a870f9db83e9ec25da7f01395eae3503f4aa1900f130
+  metadata.gz: cf505ffa08cc845661d677e1b4e5175ed12151719a68bf6e36e74899aca6c735
+  data.tar.gz: 11c57b10cf54268f70bec8eab14c4daf2ffb3abc3b10183cbe90e6e3a9bb15a5
 SHA512:
-  metadata.gz: 300fd7fe1c31e8ab0196b8a8c0d8509819ec2d0882ea3bbbc98a4c34d4aaac22d05325a4197b4fcd5f1ff79480566c7d764acbd1ee173926e31c004f4b91b510
-  data.tar.gz: d016d8f89cf2150b0a25872543603e19fdf87322ec5a9206c3aa532bf50de98f916df3a83de59c9815d530287ffcddae9236b9f4195ee8ad0c3fb3839b2dede6
+  metadata.gz: 2d6eabb97a9acb6ee7c3f61f7ccc676d7db740b7b2516583218a0902ca8fc5b4950eeb4143b1315e9adce799193f48c72bcfa9d3e625c91130bee6c3df814186
+  data.tar.gz: 194d199f07c81ef3f6d385179e79222a5dac4b0984a2a470ff5f5ac52f0097992b013f264e443fec601ad1dc37e62ff9566a2bb68bccd82d15a2defc11a5f820

data/README.md

@@ -79,6 +79,19 @@ and HTML otherwise. Other flags: `--title`, `--status draft|published`,
 `--slug`, `--published-at`, `--tags`, `--canonical-url`, `--locale` and
 `--hidden`/`--no-hidden`. `--json` prints the full response.
 
+## Agent skill
+
+The gem includes a skill that teaches coding agents such as Claude Code to use
+the CLI:
+
+```bash
+pagecord skill              # print it
+pagecord skill install      # install it for your agents
+```
+
+`install` writes it to `~/.agents/skills/pagecord` and links it into
+`~/.claude/skills`. Run it again after upgrading the gem.
+
 ## Choosing a blog
 
 With one blog configured, every command uses it. With several, set a default

data/lib/pagecord_cli/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: pagecord
+description: Manage a Pagecord blog with the `pagecord` CLI. Use when the user wants to list, read, write or edit posts, pages or drafts, publish a local Markdown or HTML file, restyle their blog (theme, font, layout, colours, custom CSS), or add custom head or footer code.
+allowed-tools: Bash, Read, Write, Edit, WebFetch
+---
+
+# Pagecord
+
+Everything here runs through the `pagecord` command. `pagecord --help` lists
+every command and flag; `pagecord version` says which version is installed.
+
+## Rules
+
+1. **Draft unless told to publish.** Pass `--status draft` to `post create` and
+   `post update`, and use `pagecord draft FILE` rather than `publish`, unless
+   the user asked to publish.
+2. **Posts and pages are addressed by token**, eight hex characters such as
+   `aaa33a9b`. `post list` shows them.
+3. **Content is HTML.** `post show` returns HTML; edit it as HTML and send it
+   back with `--content-file`. A file ending `.md` is sent as Markdown.
+4. **`custom-code update` replaces the whole field.** Save the current value
+   first and keep it as the backup.
+5. **Never create an API key.** If `pagecord blog list` prints nothing, ask the
+   user to run `pagecord login SUBDOMAIN` with a key from Settings > API.
+6. **Pass `--json` when you need to parse output.**
+
+## Quick reference
+
+| To | Run |
+|----|-----|
+| List posts | `pagecord post list [--drafts\|--published] [--page N]` |
+| Read a post | `pagecord post show TOKEN` |
+| Edit a post | `pagecord post update TOKEN --content-file F [--title T] [--status draft]` |
+| Write a post | `pagecord post create --title T --content-file F --status draft` |
+| Delete a post | `pagecord post delete TOKEN [--permanent]` |
+| Pages | `pagecord page list\|show\|create\|update\|delete`, as for posts |
+| Publish a file | `pagecord publish FILE` or `pagecord draft FILE` |
+| Theme and fonts | `pagecord appearance show\|update` |
+| Custom CSS, head, footer | `pagecord custom-code show\|update` |
+| Blogs | `pagecord blog list`, `pagecord blog use SUBDOMAIN` |
+
+With several blogs configured, pass `--blog SUBDOMAIN` or set a default with
+`pagecord blog use`. Lists return 15 at a time, newest first; `--page 2` gets
+the next 15. The home page isn't covered by the CLI yet.
+
+## Editing posts
+
+```bash
+pagecord post show TOKEN --json      # fields plus the HTML content
+pagecord post update TOKEN --content-file post.html --status draft
+```
+
+`update` changes only the flags given. Other fields: `--slug`,
+`--published-at`, `--tags "a, b"`, `--canonical-url`, `--locale`,
+`--hidden`/`--no-hidden`. Delete moves a post to the bin unless you pass
+`--permanent`, which can't be undone: confirm with the user first.
+
+## Publishing files
+
+```bash
+pagecord publish hello.md            # publish or update
+pagecord draft notes/idea.md         # save as a draft
+```
+
+The first run writes a `pagecord_token` into the file's front matter, and later
+runs update that same post. Front matter can set `title`, `slug`, `tags`,
+`published_at`, `canonical_url`, `hidden` and `locale`. Local images written as
+`![alt](photo.jpg)` are uploaded.
+
+## Restyling a blog
+
+Read https://help.pagecord.com/custom-css before the first CSS change. It
+documents every class you can target and what Pagecord accepts. Don't work out
+the structure by scraping a blog: comments load on demand and are missing from
+the page source.
+
+Look at the theme first, since your CSS has to work with it:
+
+```bash
+pagecord appearance show
+pagecord custom-code show --css > blog.css
+cp blog.css blog.css.orig
+```
+
+Edit `blog.css`, show the user a diff, then save it:
+
+```bash
+pagecord custom-code update --css blog.css
+```
+
+Undoing is `pagecord custom-code update --css blog.css.orig`; tell the user.
+
+Pagecord rejects CSS that is over 16KB, nested (`.post { .title { } }`), or
+`@import`s anything but HTTPS Google Fonts or Bunny Fonts. A rejected update
+changes nothing. Custom properties, `@supports` and `@layer` are fine.
+
+Prefer overriding the theme's custom properties, which work in light and dark
+mode, over restyling elements one by one:
+
+```css
+:root {
+  --theme-bg: #faf7f0;
+  --theme-text: #2b2b2b;
+  --theme-accent: #8c5a3c;
+  --font-body: Georgia, serif;
+  --font-size-base: 112.5%;
+}
+```
+
+Scope rules with the attributes on `<body>`: `data-page-type` is `index`,
+`home-page`, `page` or `post`, and `data-slug` is the slug being viewed. Target
+`.post-body`, never classes containing `lexxy`, which may be renamed.
+
+Whole-theme changes belong in `appearance update`, not CSS:
+`--theme`, `--font`, `--width`, `--layout`, the six `--custom-theme-*` colours
+and `--show-branding true|false`. The Theme Garden in Settings > Appearance
+applies curated designs in one click.
+
+`--footer-html`, `--head-html` and `--body-html` work like `--css` and each
+take a file path. `--enabled false` switches head and body code off without
+deleting it.
+
+## Always verify
+
+After any change, load the blog and check it. A successful update only means
+the change was saved.

data/lib/pagecord_cli/cli.rb

@@ -2,6 +2,7 @@
 
 require "io/console"
 require "json"
+require "fileutils"
 require "optparse"
 
 module PagecordCLI
@@ -21,6 +22,8 @@ module PagecordCLI
       "body-html" => "custom_body_html"
     }.freeze
 
+    SKILL_PATH = File.expand_path("SKILL.md", __dir__)
+
     attr_reader :argv, :config, :input, :output, :error, :options
 
     def initialize(argv, config: Config.new, input: $stdin, output: $stdout, error: $stderr)
@@ -34,6 +37,7 @@ module PagecordCLI
 
     def run
       return help if argv.empty? || %w[help -h --help].include?(argv.first)
+      return version if %w[version -v --version].include?(argv.first)
 
       parser.order!(argv)
       command = argv.shift
@@ -47,6 +51,7 @@ module PagecordCLI
       when "custom-code" then custom_code
       when "post" then records("posts")
       when "page" then records("pages")
+      when "skill" then skill
       when "publish" then publish("published")
       when "draft" then publish("draft")
       else
@@ -308,6 +313,34 @@ module PagecordCLI
         params
       end
 
+      def skill
+        case argv.shift
+        when nil then output.print File.read(SKILL_PATH)
+        when "install" then install_skill
+        else return fail_with("Usage: pagecord skill [install]")
+        end
+        0
+      end
+
+      def install_skill
+        dir = File.join(Dir.home, ".agents", "skills", "pagecord")
+        FileUtils.mkdir_p(dir)
+        FileUtils.cp(SKILL_PATH, dir)
+        File.write(File.join(dir, ".installed-version"), VERSION)
+        say "Installed the Pagecord skill to #{dir}"
+
+        link = File.join(Dir.home, ".claude", "skills", "pagecord")
+        return if File.symlink?(link) && File.readlink(link) == dir
+
+        if File.exist?(link) || File.symlink?(link)
+          error.puts "#{link} already exists, so Claude Code will keep using that. Remove it and run this again to use this skill."
+        else
+          FileUtils.mkdir_p(File.dirname(link))
+          File.symlink(dir, link)
+          say "Linked it into #{link}"
+        end
+      end
+
       def publish(status)
         overrides = {}
         parser do |opts|
@@ -316,7 +349,7 @@ module PagecordCLI
           opts.on("--published-at TIME") { |value| overrides[:published_at] = value }
           opts.on("--tags TAGS") { |value| overrides[:tags] = value }
           opts.on("--canonical-url URL") { |value| overrides[:canonical_url] = value }
-          opts.on("--hidden") { overrides[:hidden] = true }
+          opts.on("--[no-]hidden") { |value| overrides[:hidden] = value }
           opts.on("--locale LOCALE") { |value| overrides[:locale] = value }
         end.parse!(argv)
 
@@ -412,9 +445,17 @@ module PagecordCLI
         end
       end
 
+      def version
+        options[:json] = argv.include?("--json")
+        options[:json] ? print_json({ version: VERSION }) : output.puts("pagecord #{VERSION}")
+        0
+      end
+
       def help
         output.puts <<~HELP
           Usage:
+            pagecord version
+            pagecord skill [install]
             pagecord login SUBDOMAIN
             pagecord logout [SUBDOMAIN]
             pagecord blog list
@@ -437,21 +478,16 @@ module PagecordCLI
             --json             machine-readable output
             --quiet            suppress confirmation messages
 
-          Publish options:
+          Post options (publish, draft, post and page):
             --title TITLE
             --slug SLUG
             --published-at TIME
             --tags TAGS
             --canonical-url URL
-            --hidden
             --locale LOCALE
-
-          Post and page options:
-            --title TITLE
-            --content-file PATH (HTML, or Markdown if it ends .md)
-            --status draft|published
-            --slug, --published-at, --tags, --canonical-url, --locale
             --hidden, --no-hidden
+            --content-file PATH         post/page create and update; Markdown if it ends .md
+            --status draft|published    post/page create and update
 
           Appearance options:
             --theme, --font, --width, --layout

data/lib/pagecord_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PagecordCLI
-  VERSION = "0.3.0"
+  VERSION = "0.3.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pagecord-cli
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.2
 platform: ruby
 authors:
 - Olly Headey
@@ -20,6 +20,7 @@ files:
 - README.md
 - bin/pagecord
 - lib/pagecord_cli.rb
+- lib/pagecord_cli/SKILL.md
 - lib/pagecord_cli/cli.rb
 - lib/pagecord_cli/client.rb
 - lib/pagecord_cli/config.rb
@@ -46,7 +47,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
 summary: Publish local files to Pagecord
 test_files: []