pagecord-cli 0.3.1 → 0.3.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 282d0f9f75b00c70f396dd00494c60b0e345d8af90689fa6cd6f217ea2288c12
-  data.tar.gz: db5c120d320ed5c012c4576e7fce832879336e3b3e255ce0b494ff0ddb489e73
+  metadata.gz: 1e49c84bdd83870e36e7d68b218fd211dcae477a6b5b7afca0649785651f7bc2
+  data.tar.gz: c0f1f731273d36f8bc9626c5f5f7b3f596b34ca647187140b20afea957c88e42
 SHA512:
-  metadata.gz: 1b8f2174e7ca61cdba14e6b1accdd617da6c71c1b747c379120c6ff13955d1de26b0256ea34fecb2908e128a19eab52785abd0d2ae2d868916ac129f16d0523a
-  data.tar.gz: 872259af41ebbf97ece3a9eb859ebf4509f97568cd8027d8b5d6f813d40c5d96562ee7de51ead2e133922a64c26d2c3f0c7f7ba1896e765de969e9ee01d88f67
+  metadata.gz: 97a1e5baf19415337cf2a8d0a97bb888394f3550d2b6ce85f29e7039d1aae9ad58b30a5883f1ce63bcae691211c847eb5a84c6a074f4555cb4cf4f57e35fe812
+  data.tar.gz: 54bc9279534fe8ce1210cfa4fb3ce962b273c23ae60654d9e96065372b16bf7211e89868d16fb5cb6a63a07e75563259fe5d9d41acb9ffc1b490528712098c64

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
@@ -197,9 +210,13 @@ Action Text attachments:
 
 ```markdown
 ![Alt text](photo.jpg)
+![Alt text](my photo.jpg "A caption")
 ![[photo.jpg]]
 ```
 
+The alt text and an optional quoted caption go onto the image. Filenames can
+contain spaces.
+
 Supported local image types are JPEG, PNG, GIF, and WebP. External image URLs
 and HTML `<img>` tags are left alone.
 

data/lib/pagecord_cli/SKILL.md

@@ -0,0 +1,127 @@
+---
+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 "Caption")` are uploaded with their alt text and
+optional caption.
+
+## 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)
@@ -48,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
@@ -309,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|
@@ -423,6 +455,7 @@ module PagecordCLI
         output.puts <<~HELP
           Usage:
             pagecord version
+            pagecord skill [install]
             pagecord login SUBDOMAIN
             pagecord logout [SUBDOMAIN]
             pagecord blog list

data/lib/pagecord_cli/image_uploads.rb

@@ -1,10 +1,12 @@
 # frozen_string_literal: true
 
 require "digest"
+require "cgi/escape"
+require "uri"
 
 module PagecordCLI
   class ImageUploads
-    MARKDOWN_IMAGE = /!\[([^\]]*)\]\(([^)]+)\)/
+    MARKDOWN_IMAGE = /!\[([^\]]*)\]\(([^)"]+?)(?:\s+"([^"]*)")?\)/
     OBSIDIAN_IMAGE = /!\[\[([^\]]+)\]\]/
     IMAGE_EXTENSIONS = /\.(jpe?g|png|gif|webp)\z/i
 
@@ -20,8 +22,9 @@ module PagecordCLI
 
     def process
       with_markdown_images = content.gsub(MARKDOWN_IMAGE) do |match|
-        path = Regexp.last_match(2)
-        local_path?(path) ? attachment_tag_for(path) : match
+        alt, path, caption = Regexp.last_match.captures
+        path = decode_path(path)
+        local_path?(path) ? attachment_tag_for(path, alt: alt, caption: caption) : match
       end
 
       with_markdown_images.gsub(OBSIDIAN_IMAGE) do |match|
@@ -32,9 +35,20 @@ module PagecordCLI
 
     private
 
-      def attachment_tag_for(path)
+      def attachment_tag_for(path, alt: nil, caption: nil)
         sgid = cached_sgid(path) || upload(path)
-        %(<action-text-attachment sgid="#{sgid}"></action-text-attachment>)
+        %(<action-text-attachment sgid="#{sgid}"#{attribute("alt", alt)}#{attribute("caption", caption)}></action-text-attachment>)
+      end
+
+      def attribute(name, value)
+        %( #{name}="#{CGI.escapeHTML(value)}") unless value.to_s.empty?
+      end
+
+      # A filename can contain a literal "%", as in 100%.jpg.
+      def decode_path(path)
+        URI.decode_uri_component(path)
+      rescue ArgumentError
+        path
       end
 
       def cached_sgid(path)
@@ -74,7 +88,8 @@ module PagecordCLI
       end
 
       def checksum(path)
-        Digest::SHA256.file(path).hexdigest[0, 16]
+        @checksums ||= {}
+        @checksums[path] ||= Digest::SHA256.file(path).hexdigest[0, 16]
       end
 
       def filename(path)

data/lib/pagecord_cli/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pagecord-cli
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.3
 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